magus-cli 0.0.0-placeholder → 7.0.0

package/src/services/claude-cli.ts

@@ -0,0 +1,304 @@
+/**
+ * Claude CLI wrapper service
+ *
+ * Delegates plugin and marketplace management to the `claude` CLI
+ * instead of manipulating settings JSON files directly.
+ *
+ * CLI commands used:
+ * - claude plugin install/uninstall/enable/disable/update
+ * - claude marketplace add
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { defaultMarketplaces } from "../data/marketplaces.js";
+import { which } from "../utils/command-utils.js";
+import {
+	isMarketplaceRegistered,
+	removeGlobalInstalledPluginVersion,
+	removeLocalInstalledPluginVersion,
+} from "./claude-settings.js";
+import { removeInstalledPluginVersion } from "./plugin-manager.js";
+
+const execFileAsync = promisify(execFile);
+
+export type PluginScope = "user" | "project" | "local";
+
+/**
+ * Get the path to the claude CLI binary
+ * @throws Error if claude CLI is not found in PATH
+ */
+async function getClaudePath(): Promise<string> {
+	const claudePath = await which("claude");
+	if (!claudePath) {
+		throw new Error(
+			"claude CLI not found in PATH. Install with: npm install -g @anthropic-ai/claude-code",
+		);
+	}
+	return claudePath;
+}
+
+/**
+ * Execute a claude CLI command and return stdout
+ * @param args - Arguments to pass to claude
+ * @param timeoutMs - Timeout in milliseconds (default: 30s)
+ * @returns stdout from the command
+ */
+async function execClaude(args: string[], timeoutMs = 30000): Promise<string> {
+	const claudePath = await getClaudePath();
+	try {
+		const { stdout } = await execFileAsync(claudePath, args, {
+			timeout: timeoutMs,
+		});
+		return stdout.trim();
+	} catch (error: unknown) {
+		const execError = error as {
+			stderr?: string;
+			stdout?: string;
+			message?: string;
+			code?: number;
+		};
+		const msg =
+			execError.stderr?.trim() ||
+			execError.stdout?.trim() ||
+			execError.message ||
+			"claude command failed";
+		throw new Error(msg);
+	}
+}
+
+/**
+ * Recover from a "not found in marketplace" error.
+ *
+ * Two distinct failure modes land in the same error string:
+ *   1. Marketplace is registered locally but stale (or uses the old
+ *      "directory" source) — fix the registry and refresh the clone.
+ *   2. Marketplace is not registered at all — look up its repo in
+ *      defaultMarketplaces and add it. This is the "new employee clones
+ *      a project whose .claude/settings.json enables @magus plugins but
+ *      magus was never registered on this machine" case.
+ *
+ * Returns true if recovery was attempted and a retry is worth trying.
+ */
+async function recoverMissingMarketplace(
+	marketplace: string,
+): Promise<boolean> {
+	if (await isMarketplaceRegistered(marketplace)) {
+		// Registered but the plugin wasn't found → the registry may use a stale or
+		// "directory" source. Fix the registry, then refresh the clone
+		// NON-DESTRUCTIVELY (git pull --ff-only) — never `marketplace update`, which
+		// deletes the directory before re-cloning and can leave it permanently gone
+		// on failure (see marketplace-refresh.ts). If the clone is absent, fall
+		// through to the safe `marketplace add` below to create it.
+		const { recoverMarketplaceSettings } = await import("./claude-settings.js");
+		await recoverMarketplaceSettings();
+		const { fastForwardCloneIfPresent } = await import(
+			"./marketplace-refresh.js"
+		);
+		if ((await fastForwardCloneIfPresent(marketplace)) !== "absent") {
+			return true;
+		}
+		// Clone missing → fall through to `marketplace add`.
+	}
+
+	const defaultMp = defaultMarketplaces.find((m) => m.name === marketplace);
+	if (!defaultMp?.source.repo) return false;
+
+	await addMarketplace(defaultMp.source.repo);
+	return true;
+}
+
+/**
+ * Run a `claude plugin` subcommand, recovering once from a missing or stale
+ * marketplace.
+ *
+ * Shared by install and update because the recovery is identical and the two
+ * had already been written twice; a third copy for `update` is how the next
+ * divergence starts.
+ */
+async function execPluginCommand(
+	verb: "install" | "update",
+	pluginId: string,
+	scope: PluginScope,
+	timeoutMs?: number,
+): Promise<void> {
+	const argv = ["plugin", verb, pluginId, "--scope", scope];
+	try {
+		await execClaude(argv, timeoutMs);
+	} catch (error) {
+		const msg = error instanceof Error ? error.message : String(error);
+		if (msg.includes("not found in marketplace")) {
+			const marketplace = pluginId.split("@")[1];
+			if (marketplace && (await recoverMissingMarketplace(marketplace))) {
+				await execClaude(argv, timeoutMs);
+				return;
+			}
+		}
+		throw error;
+	}
+}
+
+/**
+ * Install a plugin using claude CLI
+ * Handles enabling + version tracking + cache copy in one shot.
+ *
+ * ONLY for a plugin that is not installed at this scope yet. On one already
+ * installed there, `claude plugin install` is a no-op that ignores the version
+ * — see {@link updatePlugin}.
+ *
+ * If the install fails because the plugin is "not found in marketplace",
+ * attempts to recover (add the marketplace if missing, or refresh it if
+ * stale) and retries once.
+ */
+export async function installPlugin(
+	pluginId: string,
+	scope: PluginScope = "user",
+): Promise<void> {
+	// 60s, matching update and repair. Before the install/update split this path
+	// ran through `updatePlugin`'s 60s budget; leaving it on the 30s default
+	// would have quietly halved the time a fresh install — the SLOWEST of the
+	// three, since it downloads and copies — is allowed to take.
+	await execPluginCommand("install", pluginId, scope, 60000);
+}
+
+/**
+ * Uninstall a plugin using claude CLI.
+ * Falls back to direct settings removal if CLI uninstall fails
+ * (e.g., for plugins installed via old JSON method).
+ * @param projectPath - Required for project/local scope fallback
+ */
+export async function uninstallPlugin(
+	pluginId: string,
+	scope: PluginScope = "user",
+	projectPath?: string,
+): Promise<void> {
+	try {
+		await execClaude(["plugin", "uninstall", pluginId, "--scope", scope]);
+	} catch {
+		// Fallback: directly remove from settings JSON
+		if (scope === "user") {
+			await removeGlobalInstalledPluginVersion(pluginId);
+		} else if (scope === "local" && projectPath) {
+			await removeLocalInstalledPluginVersion(pluginId, projectPath);
+		} else if (projectPath) {
+			await removeInstalledPluginVersion(pluginId, projectPath);
+		}
+	}
+}
+
+/**
+ * Repair a plugin whose files drifted from the marketplace under an unchanged
+ * version — uninstall, then install again at the same scope.
+ *
+ * `claude plugin install` cannot do this alone. Measured against the real
+ * `MadAppGang/magus` marketplace (autotest/plugin-system/probe-05): with the
+ * version unchanged it reports *"Plugin is already installed"* and copies
+ * nothing — cache content and the recorded `gitCommitSha` both stay put.
+ * Uninstall-then-install refreshes both. That is why the only cure users ever
+ * found was removing the plugin and adding it back.
+ *
+ * The window between the two calls is real: if the install fails, the plugin is
+ * left uninstalled. The caller must surface that rather than swallow it, which
+ * is why the install error is rethrown with the state spelled out.
+ */
+export async function repairPlugin(
+	pluginId: string,
+	scope: PluginScope = "user",
+	projectPath?: string,
+): Promise<void> {
+	await uninstallPlugin(pluginId, scope, projectPath);
+	try {
+		await execClaude(["plugin", "install", pluginId, "--scope", scope], 60000);
+	} catch (error) {
+		const msg = error instanceof Error ? error.message : String(error);
+		throw new Error(
+			`${pluginId} was uninstalled from ${scope} scope but could not be reinstalled: ${msg}. Reinstall it manually with: claude plugin install ${pluginId} --scope ${scope}`,
+		);
+	}
+}
+
+/**
+ * Enable a previously disabled plugin
+ */
+export async function enablePlugin(
+	pluginId: string,
+	scope: PluginScope = "user",
+): Promise<void> {
+	await execClaude(["plugin", "enable", pluginId, "--scope", scope]);
+}
+
+/**
+ * Disable a plugin without uninstalling it
+ */
+export async function disablePlugin(
+	pluginId: string,
+	scope: PluginScope = "user",
+): Promise<void> {
+	await execClaude(["plugin", "disable", pluginId, "--scope", scope]);
+}
+
+/**
+ * Update an ALREADY-INSTALLED plugin to the latest version.
+ *
+ * Runs `claude plugin update`, not `claude plugin install`.
+ *
+ * This used to run `install`, on the documented premise that it "handles both
+ * fresh installs and re-installs (upgrades) of existing plugins". That premise
+ * is false, and every magus update path was silently doing nothing because
+ * of it. Measured against Claude Code 2.1.252, with designer@magus at 0.6.0 and
+ * 0.6.1 published:
+ *
+ *     $ claude plugin install designer@magus --scope project
+ *     Installing plugin "designer@magus"...
+ *     ✔ Plugin "designer@magus" is already installed (scope: project)
+ *     EXIT: 0
+ *
+ *     $ claude plugin update designer@magus --scope project
+ *     Checking for updates for plugin "designer@magus" at project scope…
+ *     ✔ Plugin "designer" updated from 0.6.0 to 0.6.1 for scope project. Restart to apply.
+ *     EXIT: 0
+ *
+ * `install` is idempotent on (plugin, scope) and never looks at the version, so
+ * it exits 0 having done nothing — indistinguishable from success to every
+ * caller. The registry keeps the old version, the read-back in `update-engine`
+ * records that old version as "what landed", and the same update is offered
+ * again on the next run, for ever.
+ *
+ * The two commands are NOT interchangeable in the other direction either:
+ * `claude plugin update` on a plugin absent from this scope reports "already at
+ * the latest version" and installs nothing. A fresh install must go through
+ * {@link installPlugin}, and content drift under an unchanged version still
+ * needs {@link repairPlugin} — `update` has no version bump to act on there.
+ *
+ * Retries with marketplace update on "not found" errors (same as installPlugin).
+ */
+export async function updatePlugin(
+	pluginId: string,
+	scope: PluginScope = "user",
+): Promise<void> {
+	await execPluginCommand("update", pluginId, scope, 60000);
+}
+
+/**
+ * Add a marketplace by GitHub repo (e.g., "MadAppGang/magus")
+ * Uses longer timeout since this involves cloning a git repo
+ */
+export async function addMarketplace(repo: string): Promise<void> {
+	await execClaude(["plugin", "marketplace", "add", repo], 60000);
+}
+
+/**
+ * Update marketplace cache by running git pull via Claude CLI
+ * Uses longer timeout since this involves git network operations
+ */
+export async function updateMarketplace(name: string): Promise<void> {
+	await execClaude(["plugin", "marketplace", "update", name], 60000);
+}
+
+/**
+ * Check if the claude CLI is available
+ * @returns true if claude CLI is found in PATH
+ */
+export async function isClaudeAvailable(): Promise<boolean> {
+	return (await which("claude")) !== null;
+}

package/src/services/claude-runner.ts

@@ -0,0 +1,31 @@
+import { spawn } from "node:child_process";
+import { which } from "../utils/command-utils.js";
+
+/**
+ * Execute claude CLI with provided arguments
+ * @param args - Arguments to pass to claude
+ * @returns Exit code from claude process
+ */
+export async function runClaude(args: string[]): Promise<number> {
+	// Check if claude exists
+	const claudePath = await which("claude");
+	if (!claudePath) {
+		console.error("Error: claude CLI not found in PATH");
+		console.error("Install with: npm install -g @anthropic-ai/claude-code");
+		return 1;
+	}
+
+	// Spawn claude with full TTY inheritance using the resolved path
+	return new Promise((resolve) => {
+		const proc = spawn(claudePath, args, {
+			stdio: "inherit", // Pass through stdin, stdout, stderr
+			shell: false, // Use full path, no shell needed (fixes DEP0190)
+		});
+
+		proc.on("exit", (code) => resolve(code || 0));
+		proc.on("error", (err) => {
+			console.error("Failed to run claude:", err.message);
+			resolve(1);
+		});
+	});
+}