magus-cli 7.12.2 → 7.14.0

package/src/ui/renderers/pluginRenderers.tsx

@@ -132,7 +132,9 @@ function categoryDetail(
 			<text fg={isEnabled ? theme.colors.success : theme.colors.muted}>
 				{isEnabled ? "● Added" : "○ Not added"}
 			</text>
-			<text fg={theme.colors.info}>github.com/{mp.source.repo}</text>
+			{mp.source.repo ? (
+				<text fg={theme.colors.info}>github.com/{mp.source.repo}</text>
+			) : null}
 			<text fg={theme.colors.text}>Plugins: {item.pluginCount}</text>
 			<ActionHints
 				hints={[
@@ -328,7 +330,12 @@ function StatusLine({
 			? `→ v${status.target}`
 			: "";
 	// Moved or still required: kept on purpose, which is known — never UNKNOWN.
-	const label = isKeptDeprecated(status) ? "KEPT" : ACTION_LABEL[status.action];
+	// Left out of updates for its marketplace: known too.
+	const label = isKeptDeprecated(status)
+		? "KEPT"
+		: status.reason === "marketplace-conflict"
+			? "LEFT OUT"
+			: ACTION_LABEL[status.action];
 	return (
 		<KeyValueLine
 			label="Status"
@@ -571,7 +578,28 @@ function pluginDetail(
 
 			{/* Metadata */}
 			<StatusLine status={status} />
-			{showVersion ? (
+			{/*
+			 * Left out: the version this catalog offers is the other repository's,
+			 * so it is not shown as one to install. What is installed here, and
+			 * that updates leave it alone, is.
+			 */}
+			{status?.reason === "marketplace-conflict" ? (
+				<KeyValueLine
+					label="Version"
+					value={
+						<span>
+							{status.installed ? (
+								<span fg={theme.colors.info}>
+									v{status.installed} installed
+								</span>
+							) : (
+								<span fg={theme.colors.muted}>not installed</span>
+							)}
+							<span fg={theme.colors.warning}> · left out of updates</span>
+						</span>
+					}
+				/>
+			) : showVersion ? (
 				<KeyValueLine
 					label="Version"
 					value={

package/src/ui/renderers/pluginStatusText.ts

@@ -40,6 +40,12 @@ export function pluginStatusText(
 		};
 	}
 
+	// Left out of every update: its marketplace here is not the profile's. A
+	// fact that needs a look, so amber, and never the "?" of "cannot tell".
+	if (status.reason === "marketplace-conflict") {
+		return { suffix: ` left out — ${status.note ?? ""}`, tone: "warning" };
+	}
+
 	switch (status.action) {
 		case "unknown":
 			// Amber, not red: "cannot tell" is not a failure.

package/src/ui/screens/PluginsScreen.tsx

@@ -12,6 +12,12 @@ import {
 } from "../../services/claude-cli.js";
 import { readSettings, setMcpEnvVar } from "../../services/claude-settings.js";
 import { clearContentDriftCache } from "../../services/content-drift.js";
+import {
+	type MarketplaceCheck,
+	NOTHING_LEFT_OUT,
+	leftOutWhy,
+} from "../../services/marketplace-conflicts.js";
+import { conflictFix } from "../../services/marketplace-sync.js";
 import { missingPluginEnvVars } from "../../services/plugin-env-needs.js";
 import {
 	type MarketplaceFetchFailure,
@@ -179,6 +185,13 @@ export function PluginsScreen() {
 	const [listedByProfiles, setListedByProfiles] = useState<readonly string[]>(
 		[],
 	);
+	/**
+	 * The profile's marketplaces whose plugins `magus update` leaves out here,
+	 * found without changing anything: their rows say so, and no update or
+	 * install is planned for them.
+	 */
+	const [marketplaceCheck, setMarketplaceCheck] =
+		useState<MarketplaceCheck>(NOTHING_LEFT_OUT);
 
 	// Fetch data (always fetches all scopes). Only the most recently started
 	// load may touch the screen.
@@ -213,6 +226,7 @@ export function PluginsScreen() {
 			setActiveProfileId(active?.profileId ?? null);
 			setRequiredBy(required);
 			setListedByProfiles(active?.listedByProfiles ?? []);
+			setMarketplaceCheck(active?.marketplaces ?? NOTHING_LEFT_OUT);
 
 			// Which catalogs answered, and which only appeared to. Read straight
 			// after the fetch, while the record still describes this attempt.
@@ -309,9 +323,10 @@ export function PluginsScreen() {
 						pins ?? {},
 						requiredBy,
 						listedByProfiles,
+						(pluginId) => leftOutWhy(pluginId, marketplaceCheck),
 					)
 				: new Map(),
-		[shownPlugins, pins, requiredBy, listedByProfiles],
+		[shownPlugins, pins, requiredBy, listedByProfiles, marketplaceCheck],
 	);
 
 	/**
@@ -754,7 +769,7 @@ export function PluginsScreen() {
 			if (choice === null) return;
 			if (choice) {
 				try {
-					await cliAddMarketplace(choice);
+					await cliAddMarketplace(choice, "user");
 					await handleRefresh();
 				} catch (e) {
 					await modal.failures(addMarketplaceFailure(choice, e));
@@ -909,6 +924,25 @@ export function PluginsScreen() {
 		}
 	};
 
+	/**
+	 * A row `magus update` leaves out — its marketplace here is not the one the
+	 * profile names, or could not be compared — takes no install, update,
+	 * removal or scope change from any key: what this machine would install is
+	 * the other repository's plugin. The one popup says so; no claude command
+	 * runs. True when the key was refused.
+	 */
+	const refuseLeftOut = async (plugin: PluginInfo): Promise<boolean> => {
+		const status = statuses.get(plugin.id);
+		if (status?.reason !== "marketplace-conflict") return false;
+		const conflicted = marketplaceCheck.conflicted.has(plugin.marketplace);
+		await modal.failures({
+			headline: `${plugin.name} is left out — nothing was changed`,
+			rows: [{ subject: plugin.name, reason: status.note ?? "left out" }],
+			fix: conflicted ? conflictFix(plugin.marketplace) : null,
+		});
+		return true;
+	};
+
 	const handleSelect = async () => {
 		const item = selectableItems[pluginsState.selectedIndex];
 		if (!item) return;
@@ -940,7 +974,7 @@ export function PluginsScreen() {
 				);
 				if (wantAdd) {
 					try {
-						await cliAddMarketplace(repo);
+						await cliAddMarketplace(repo, "user");
 						await handleRefresh();
 					} catch (e) {
 						await modal.failures(addMarketplaceFailure(repo, e));
@@ -949,6 +983,7 @@ export function PluginsScreen() {
 			}
 		} else if (item.kind === "plugin") {
 			const plugin = item.plugin;
+			if (await refuseLeftOut(plugin)) return;
 			const status = statuses.get(plugin.id);
 
 			// The label's arrow and what the key then does are ONE rule —
@@ -1088,6 +1123,7 @@ export function PluginsScreen() {
 	const handleUpdate = async () => {
 		const item = selectableItems[pluginsState.selectedIndex];
 		if (!item || item.kind !== "plugin") return;
+		if (await refuseLeftOut(item.plugin)) return;
 		// The row said "update", "stale — reinstall" or "BROKEN"; nothing else is
 		// work for this key. `install` stays out — that is the scope keys' and the
 		// profile's business, and the detail panel never offers U for it.
@@ -1180,6 +1216,7 @@ export function PluginsScreen() {
 	const handleScopeToggle = async (scope: "user" | "project" | "local") => {
 		const item = selectableItems[pluginsState.selectedIndex];
 		if (!item || item.kind !== "plugin") return;
+		if (await refuseLeftOut(item.plugin)) return;
 
 		const plugin = item.plugin;
 		const scopeLabel =
@@ -1253,6 +1290,7 @@ export function PluginsScreen() {
 	const handleRemoveDeprecated = async () => {
 		const item = selectableItems[pluginsState.selectedIndex];
 		if (!item || item.kind !== "plugin" || !item.plugin.isOrphaned) return;
+		if (await refuseLeftOut(item.plugin)) return;
 
 		const plugin = item.plugin;
 
@@ -1425,8 +1463,14 @@ export function PluginsScreen() {
 	// "cannot tell rendered as fine" bug.
 	// Moved or still-required plugins are `unknown` to the planner but known to
 	// the user — kept on purpose — so they are not counted as "unverified".
+	// Left out for their marketplace: known too, and counted in their own words.
+	const leftOutCount = [...statuses.values()].filter(
+		(s) => s.reason === "marketplace-conflict",
+	).length;
 	const unknownCount =
-		counts.unknown - [...statuses.values()].filter(isKeptDeprecated).length;
+		counts.unknown -
+		[...statuses.values()].filter(isKeptDeprecated).length -
+		leftOutCount;
 	const installCount = counts.install;
 	// Broken: installed at the right version, loading an older one. Its own
 	// number, never folded into `updateCount` or into silence — a clean header
@@ -1439,7 +1483,7 @@ export function PluginsScreen() {
 	// No longer published, and `a` removes them. Counted where the rows can be
 	// seen to need work; they used to sit inside "unverified".
 	const deprecatedCount = counts.remove;
-	const subtitle = `${scopeLabel} │ ${installedCount} installed${updateCount > 0 ? ` │ ${updateCount} updates` : ""}${installCount > 0 ? ` │ ${installCount} to install` : ""}${brokenCount > 0 ? ` │ ${brokenCount} broken` : ""}${deprecatedCount > 0 ? ` │ ${deprecatedCount} deprecated` : ""}${unknownCount > 0 ? ` │ ${unknownCount} unverified` : ""}`;
+	const subtitle = `${scopeLabel} │ ${installedCount} installed${updateCount > 0 ? ` │ ${updateCount} updates` : ""}${installCount > 0 ? ` │ ${installCount} to install` : ""}${brokenCount > 0 ? ` │ ${brokenCount} broken` : ""}${deprecatedCount > 0 ? ` │ ${deprecatedCount} deprecated` : ""}${leftOutCount > 0 ? ` │ ${leftOutCount} left out` : ""}${unknownCount > 0 ? ` │ ${unknownCount} unverified` : ""}`;
 	const searchPlaceholder = `${scopeLabel} │ ${installedCount} installed${updateCount > 0 ? ` │ ${updateCount} ⬆` : ""}${installCount > 0 ? ` │ ${installCount} +` : ""}${brokenCount + deprecatedCount > 0 ? ` │ ${brokenCount + deprecatedCount} ✗` : ""}${unknownCount > 0 ? ` │ ${unknownCount} ?` : ""} │ / to search`;
 
 	const catalogNotice = buildCatalogNotice({

package/src/ui/screens/SkillsScreen.tsx

@@ -1,4 +1,3 @@
-import os from "node:os";
 import path from "node:path";
 import fs from "fs-extra";
 import React, {
@@ -27,6 +26,7 @@ import {
 	fetchAvailableSkills,
 	fetchSkillFrontmatter,
 	fetchSkillSetSkills,
+	getUserSkillsDir,
 	installSkill,
 	readLocalSkillFrontmatter,
 	uninstallSkill,
@@ -213,7 +213,7 @@ export function SkillsScreen() {
 		const user = new Map<string, SkillFrontmatter | null>();
 		const project = new Map<string, SkillFrontmatter | null>();
 		const unreadable: FailureRow[] = [];
-		const userDir = path.join(os.homedir(), ".claude", "skills");
+		const userDir = getUserSkillsDir();
 		const projDir = path.join(
 			state.projectPath || process.cwd(),
 			".claude",

package/src/ui/state/AppContext.tsx

@@ -6,6 +6,7 @@ import {
 	useContext,
 	useReducer,
 } from "react";
+import type { HelpSection } from "../keymap.js";
 import { appReducer, initialState } from "./reducer.js";
 import type {
 	AppAction,
@@ -15,6 +16,7 @@ import type {
 	ProgressState,
 	Route,
 	Screen,
+	SelectOption,
 } from "./types.js";
 
 // ============================================================================
@@ -144,7 +146,11 @@ export function useModal() {
 			dispatch({ type: "HIDE_MODAL" });
 		},
 
-		confirm: (title: string, message: string): Promise<boolean> => {
+		confirm: (
+			title: string,
+			message: string,
+			details?: readonly string[],
+		): Promise<boolean> => {
 			return new Promise((resolve) => {
 				dispatch({
 					type: "SHOW_MODAL",
@@ -152,6 +158,7 @@ export function useModal() {
 						type: "confirm",
 						title,
 						message,
+						...(details ? { details } : {}),
 						onConfirm: () => {
 							dispatch({ type: "HIDE_MODAL" });
 							resolve(true);
@@ -194,7 +201,7 @@ export function useModal() {
 		select: (
 			title: string,
 			message: string,
-			options: { label: string; value: string; description?: string }[],
+			options: SelectOption[],
 			defaultIndex?: number,
 		): Promise<string | null> => {
 			return new Promise((resolve) => {
@@ -275,6 +282,11 @@ export function useModal() {
 		help: (screen: Screen) => {
 			dispatch({ type: "SHOW_MODAL", modal: { type: "help", screen } });
 		},
+
+		/** The key help overlay of an app with its own keymap: exactly `sections`. */
+		helpSections: (sections: readonly HelpSection[]) => {
+			dispatch({ type: "SHOW_MODAL", modal: { type: "help", sections } });
+		},
 	};
 }
 

package/src/ui/state/types.ts

@@ -12,6 +12,7 @@ import type {
 	ProfileEntry,
 	SkillInfo,
 } from "../../types/index.js";
+import type { HelpSection } from "../keymap.js";
 import type { ReportBadgeKind } from "../theme-mode.js";
 
 // ============================================================================
@@ -120,6 +121,8 @@ export type ModalState =
 			type: "confirm";
 			title: string;
 			message: string;
+			/** What confirming does, one line each — a plan, drawn as a list. */
+			details?: readonly string[];
 			onConfirm: () => void;
 			onCancel: () => void;
 	  }
@@ -173,9 +176,13 @@ export type ModalState =
 			message: string;
 	  }
 	| {
-			/** The key help overlay, opened with `?`, listing `screen` first. */
+			/**
+			 * The key help overlay, opened with `?`: `screen` first, from the main
+			 * keymap — or, in an app with its own keymap, exactly `sections`.
+			 */
 			type: "help";
-			screen: Screen;
+			screen?: Screen;
+			sections?: readonly HelpSection[];
 	  };
 
 // ============================================================================

package/src/utils/config-dir.ts

@@ -1,15 +1,26 @@
 /**
  * config-dir.ts — where Claude Code's config lives, with a test guard.
  *
- * `CLAUDE_CONFIG_DIR` is Claude Code's own override and must be honoured. It is
- * resolved per call rather than captured at import time, because a module-level
- * `os.homedir()` bakes in the operator's real directory and cannot be overridden
- * afterwards.
+ * `CLAUDE_CONFIG_DIR` is Claude Code's own override and must be honoured: Claude
+ * Code keeps everything under it — `settings.json`, `skills/`, and `plugins/`
+ * with the registry, the marketplace clones and the cache. Reading any of those
+ * from one root and the rest from another makes installed flags and installed
+ * versions disagree, so every reader resolves through this file.
+ *
+ * Resolved per call rather than captured at import time, because a
+ * module-level path bakes in the operator's real directory and cannot be
+ * overridden afterwards.
+ *
+ * Without `CLAUDE_CONFIG_DIR` the root is `<HOME>/.claude`, with `HOME` read at
+ * call time and `os.homedir()` only as the fallback: under Bun `os.homedir()`
+ * answers the home the process started with and ignores a later
+ * `process.env.HOME` (measured on Bun 1.4; Node follows the change).
  *
  * The test guard
  * --------------
- * Under `bun test`, a missing `CLAUDE_CONFIG_DIR` returns null instead of
- * `~/.claude`. Callers treat null as "no cache, no clone" — an empty, inert state.
+ * Under `bun test`, a missing `CLAUDE_CONFIG_DIR` makes `claudeConfigDirOrNull`
+ * return null instead of `~/.claude`. Callers treat null as "no cache, no
+ * clone" — an empty, inert state.
  *
  * This is not defensive decoration. Once the catalog cache and the rate-limit
  * cooldown moved to disk, and the catalog resolver gained a `git fetch` fallback,
@@ -25,6 +36,11 @@
 import os from "node:os";
 import path from "node:path";
 
+/** `HOME` at call time, else the home the process started with. */
+function homeDir(): string {
+	return process.env.HOME || os.homedir();
+}
+
 /**
  * The Claude config directory, or null when a test has not chosen one.
  *
@@ -36,10 +52,14 @@ export function claudeConfigDirOrNull(): string | null {
 	const explicit = process.env.CLAUDE_CONFIG_DIR;
 	if (explicit) return explicit;
 	if (process.env.NODE_ENV === "test") return null;
-	return path.join(os.homedir(), ".claude");
+	return path.join(homeDir(), ".claude");
 }
 
-/** The Claude config directory, falling back to `~/.claude` even under test. */
+/**
+ * The Claude config directory: `CLAUDE_CONFIG_DIR`, else `<HOME>/.claude`,
+ * even under test. The one root for every Claude Code file magus reads: plugin
+ * state, USER `settings.json` and USER skills.
+ */
 export function requireClaudeConfigDir(): string {
-	return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+	return process.env.CLAUDE_CONFIG_DIR || path.join(homeDir(), ".claude");
 }

package/src/utils/display-path.ts

@@ -0,0 +1,33 @@
+/**
+ * display-path.ts — a folder as a person reads it: relative to the project
+ * when it is inside it, `~/…` when it is under the home folder, else as is.
+ * For display only; JSON and every file operation keep the absolute path.
+ */
+
+import os from "node:os";
+import path from "node:path";
+
+/** `child` is `parent` itself or somewhere under it. */
+function within(parent: string, child: string): string | null {
+	const rel = path.relative(parent, child);
+	if (rel === "") return "";
+	if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
+	return rel;
+}
+
+/**
+ * `abs` shortened for display: `.claude/skills/greet` inside `cwd`,
+ * `~/.claude/skills/team-tools` under the home folder, otherwise unchanged.
+ * The home folder is `$HOME` when set, as Claude Code and the shell read it.
+ */
+export function displayPath(
+	abs: string,
+	cwd: string,
+	home: string = process.env.HOME || os.homedir(),
+): string {
+	const inProject = within(path.resolve(cwd), path.resolve(abs));
+	if (inProject !== null) return inProject === "" ? "." : inProject;
+	const inHome = home ? within(path.resolve(home), path.resolve(abs)) : null;
+	if (inHome !== null) return inHome === "" ? "~" : `~/${inHome}`;
+	return abs;
+}