magus-cli 7.12.2 → 7.14.0

package/src/services/claude-cli.ts

@@ -160,7 +160,7 @@ async function recoverMissingMarketplace(
 	const defaultMp = defaultMarketplaces.find((m) => m.name === marketplace);
 	if (!defaultMp?.source.repo) return false;
 
-	await addMarketplace(defaultMp.source.repo);
+	await addMarketplace(defaultMp.source.repo, "user");
 	return true;
 }
 
@@ -180,7 +180,7 @@ async function execPluginCommand(
 ): Promise<void> {
 	const argv = ["plugin", verb, pluginId, "--scope", scope];
 	try {
-		await execClaude(argv, timeoutMs);
+		await runPluginVerb(verb, pluginId, scope, undefined, timeoutMs);
 	} catch (error) {
 		const msg = error instanceof Error ? error.message : String(error);
 		if (msg.includes("not found in marketplace")) {
@@ -387,19 +387,149 @@ export async function updatePlugin(
 }
 
 /**
- * Add a marketplace by GitHub repo (e.g., "MadAppGang/magus")
- * Uses longer timeout since this involves cloning a git repo
+ * Register a marketplace: `claude plugin marketplace add <source> --scope
+ * <scope>`. `source` is anything Claude Code accepts — `owner/repo`, an https
+ * git URL, or a path to a marketplace directory. The scope is required so no
+ * caller declares one by accident. Longer timeout: this clones.
+ *
+ * There is deliberately no wrapper for `claude plugin marketplace update`: it
+ * deletes the clone before re-cloning and can leave it gone for good. A clone
+ * is refreshed with `fastForwardCloneIfPresent` instead.
+ */
+export async function addMarketplace(
+	source: string,
+	scope: PluginScope,
+): Promise<void> {
+	await execClaude(
+		["plugin", "marketplace", "add", source, "--scope", scope],
+		60000,
+	);
+}
+
+/**
+ * Remove a marketplace from every settings scope: `claude plugin marketplace
+ * remove <name>`. Claude Code uninstalls every plugin it provided.
  */
-export async function addMarketplace(repo: string): Promise<void> {
-	await execClaude(["plugin", "marketplace", "add", repo], 60000);
+export async function removeMarketplace(name: string): Promise<void> {
+	await execClaude(["plugin", "marketplace", "remove", name], 60000);
 }
 
 /**
- * Update marketplace cache by running git pull via Claude CLI
- * Uses longer timeout since this involves git network operations
+ * Run `claude plugin install|update <id> --scope <scope>` and nothing else.
+ *
+ * No recovery on "not found in marketplace": the recovery behind
+ * {@link installPlugin} and {@link updatePlugin} edits
+ * `known_marketplaces.json` directly, so a caller that must change Claude
+ * Code's state only through its CLI runs this and reports the error.
+ *
+ * `cwd` is where Claude Code resolves project and local scope; it defaults to
+ * this process's working directory.
  */
-export async function updateMarketplace(name: string): Promise<void> {
-	await execClaude(["plugin", "marketplace", "update", name], 60000);
+export async function runPluginVerb(
+	verb: "install" | "update",
+	pluginId: string,
+	scope: PluginScope,
+	cwd?: string,
+	timeoutMs = 60000,
+): Promise<void> {
+	await execClaude(
+		["plugin", verb, pluginId, "--scope", scope],
+		timeoutMs,
+		cwd,
+	);
+}
+
+/** One row of `claude plugin marketplace list --json`. */
+export interface CliMarketplace {
+	name: string;
+	source: string;
+	repo?: string;
+	url?: string;
+	path?: string;
+	installLocation?: string;
+}
+
+/** `claude plugin marketplace list --json`. */
+export async function listMarketplaces(): Promise<CliMarketplace[]> {
+	const out = await execClaude(["plugin", "marketplace", "list", "--json"]);
+	return parseJsonArray<CliMarketplace>(out, "marketplace list").filter(
+		(m) => typeof m?.name === "string",
+	);
+}
+
+/** One row of `claude plugin list --json`. */
+export interface CliPlugin {
+	id: string;
+	version?: string;
+	scope: PluginScope;
+	enabled?: boolean;
+	installPath?: string;
+	projectPath?: string;
+}
+
+/** `claude plugin list --json`, run in `cwd` when given. */
+export async function listPlugins(cwd?: string): Promise<CliPlugin[]> {
+	const out = await execClaude(["plugin", "list", "--json"], 30000, cwd);
+	return parseJsonArray<CliPlugin>(out, "plugin list").filter(
+		(p) => typeof p?.id === "string",
+	);
+}
+
+function parseJsonArray<T>(out: string, what: string): T[] {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(out || "[]");
+	} catch (error) {
+		throw new Error(
+			`claude ${what} --json printed something that is not JSON`,
+			{ cause: error },
+		);
+	}
+	if (!Array.isArray(parsed)) {
+		throw new Error(`claude ${what} --json did not print a list`);
+	}
+	return parsed as T[];
+}
+
+/** What `claude plugin validate` said about a directory. */
+export interface ValidateResult {
+	ok: boolean;
+	output: string;
+}
+
+/**
+ * `claude plugin validate <dir>`, plain — never `--strict`, which fails on the
+ * company marker and on a marketplace with no plugins yet. The exit code is
+ * the gate; the output is kept for the report either way.
+ */
+export async function validatePath(dir: string): Promise<ValidateResult> {
+	try {
+		const output = await execClaude(["plugin", "validate", dir], 60000);
+		return { ok: true, output };
+	} catch (error) {
+		return {
+			ok: false,
+			output: error instanceof Error ? error.message : String(error),
+		};
+	}
+}
+
+/**
+ * The next step when `claude plugin marketplace add` failed on GitHub
+ * credentials, or null when it failed for another reason. Claude Code clones
+ * with plain git, so a gh sign-in alone is not enough: git must also use gh's
+ * credentials, which `gh auth setup-git` arranges.
+ */
+export function marketplaceAddHint(error: unknown): string | null {
+	const message = error instanceof Error ? error.message : String(error);
+	if (
+		/terminal prompts disabled|could not read (Username|Password)|Authentication failed|Invalid username or password|Permission denied \(publickey|Repository not found|returned error: 40[13]/i.test(
+			message,
+		)
+	) {
+		return "Run `gh auth login`, then `gh auth setup-git`, and try again.";
+	}
+	return null;
 }
 
 /**

package/src/services/claude-settings.ts

@@ -1,4 +1,3 @@
-import os from "node:os";
 import path from "node:path";
 import fs from "fs-extra";
 import semver from "semver";
@@ -11,6 +10,7 @@ import type {
 	MarketplaceSource,
 	McpServerConfig,
 } from "../types/index.js";
+import { requireClaudeConfigDir } from "../utils/config-dir.js";
 import { parsePluginId } from "../utils/string-utils.js";
 import { repoHeadSha } from "./content-drift.js";
 import { inheritablePaths } from "./git-worktree.js";
@@ -61,16 +61,14 @@ export function getClaudeDir(projectPath?: string): string {
 }
 
 /**
- * `~/.claude`, resolved per call.
- *
- * `HOME` first, then `os.homedir()` — Node's own rule for `os.homedir()`, done
- * by hand because Bun does not follow it: under Bun 1.4 `os.homedir()` answers
- * the home the process started with and ignores a later `process.env.HOME`
- * (measured; Node follows the change). Reading `HOME` at call time is what lets
- * a caller — a test above all — point the global settings somewhere else.
+ * Claude Code's USER config directory, resolved per call through
+ * {@link requireClaudeConfigDir}: `CLAUDE_CONFIG_DIR` when set, else
+ * `<HOME>/.claude` with `HOME` read at call time. Claude Code keeps USER
+ * `settings.json` there as well as its plugin state, so both come from one
+ * root and a caller — a test above all — moves them together.
  */
 export function getGlobalClaudeDir(): string {
-	return path.join(process.env.HOME || os.homedir(), CLAUDE_DIR);
+	return requireClaudeConfigDir();
 }
 
 export async function ensureClaudeDir(projectPath?: string): Promise<string> {
@@ -1070,13 +1068,13 @@ export async function discoverAllGlobalMarketplaces(): Promise<
  * path it writes still names the operator's real home.
  */
 export const pluginsDir = (): string =>
-	path.join(os.homedir(), ".claude", "plugins");
+	path.join(requireClaudeConfigDir(), "plugins");
 
 const installedPluginsFile = (root: string = pluginsDir()): string =>
 	path.join(root, "installed_plugins.json");
 
 const knownMarketplacesFile = (): string =>
-	path.join(os.homedir(), ".claude", "plugins", "known_marketplaces.json");
+	path.join(pluginsDir(), "known_marketplaces.json");
 
 interface KnownMarketplaceEntry {
 	source: { source: string; path?: string; repo?: string };
@@ -1160,12 +1158,7 @@ export async function recoverMarketplaceSettings(): Promise<MarketplaceRecoveryR
 		if (entry.source?.source === "directory") {
 			const defaultMp = defaultMarketplaces.find((m) => m.name === name);
 			if (defaultMp?.source.repo) {
-				const marketplacesDir = path.join(
-					os.homedir(),
-					".claude",
-					"plugins",
-					"marketplaces",
-				);
+				const marketplacesDir = path.join(pluginsDir(), "marketplaces");
 				entry.source = {
 					source: "github",
 					repo: defaultMp.source.repo,
@@ -1209,14 +1202,15 @@ async function readKnownMarketplaces(): Promise<KnownMarketplaces> {
  */
 export async function isMarketplaceRegistered(name: string): Promise<boolean> {
 	const known = await readKnownMarketplaces();
-	if (!known[name]) return false;
-	const marketplacesDir = path.join(
-		os.homedir(),
-		".claude",
-		"plugins",
-		"marketplaces",
-	);
-	return fs.pathExists(path.join(marketplacesDir, name));
+	const entry = known[name];
+	if (!entry) return false;
+	// A `directory` marketplace is read where it is: it has no clone under
+	// plugins/marketplaces, and its own folder is what must exist.
+	const where =
+		entry.source.source === "directory" && entry.source.path
+			? entry.source.path
+			: path.join(pluginsDir(), "marketplaces", name);
+	return fs.pathExists(where);
 }
 
 /**

package/src/services/doctor.ts

@@ -15,6 +15,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import type { PluginConventions } from "../types/index.js";
+import { requireClaudeConfigDir } from "../utils/config-dir.js";
 import { parsePluginId } from "../utils/string-utils.js";
 import { readInstalledPluginsRegistry } from "./claude-settings.js";
 import {
@@ -70,10 +71,9 @@ export type DoctorLogger = (
 // INTERNAL HELPERS
 // ============================================================
 
-import { homedir } from "node:os";
-
-/** Path constants matching plugin-manager.ts */
-const MARKETPLACES_DIR = join(homedir(), ".claude", "plugins", "marketplaces");
+/** Claude Code's marketplace clones, resolved per call. */
+const marketplacesDir = (): string =>
+	join(requireClaudeConfigDir(), "plugins", "marketplaces");
 
 /**
  * Resolve a plugin ID to its filesystem source path.
@@ -92,7 +92,7 @@ async function resolvePluginPath(pluginId: string): Promise<string | null> {
 	if (!localPlugin?.source || typeof localPlugin.source !== "string")
 		return null;
 
-	const marketplacePath = join(MARKETPLACES_DIR, mpName);
+	const marketplacePath = join(marketplacesDir(), mpName);
 	const pluginPath = join(
 		marketplacePath,
 		localPlugin.source.replace("./", ""),