magus-cli 0.0.0-placeholder → 7.1.0

package/src/ui/theme.ts

@@ -0,0 +1,175 @@
+import { RGBA } from "@opentui/core";
+
+/**
+ * magus's palette: our own vivid accents, on the terminal's own canvas.
+ *
+ * Three rules, and the reason for each:
+ *
+ *  1. **Backgrounds are never ours.** Surfaces and modals use the terminal's
+ *     background. Painting an absolute fill boxes the UI into whichever theme we
+ *     guessed, and it was the original sin here — modals hardcoded #1C1C1E.
+ *  2. **Body text is never ours.** Normal text uses the terminal's foreground,
+ *     which is the only colour guaranteed to clear a text-grade contrast ratio
+ *     against that terminal's own background. `text` used to be the string
+ *     `"white"` — OpenTUI resolves that to rgb(255,255,255), not to "the
+ *     terminal's white" — so on a light theme every installed plugin was drawn
+ *     white-on-cream and vanished while the *un*installed ones, in grey, stayed
+ *     readable. The list read exactly backwards.
+ *  3. **Accents ARE ours, and vivid.** Deferring accents to ANSI slots 0-15 made
+ *     everything legible but flattened it: a theme that renders slots 2 and 3 as
+ *     neighbouring olives leaves user/project/local scope squares indistinguishable,
+ *     and slot 8 chips melt into the page. Distinction is a product decision, so
+ *     these are chosen, not inherited.
+ *
+ * ## How the accents were chosen
+ *
+ * By measurement, not taste. A single colour CANNOT reach 4.5:1 against both a
+ * light and a dark terminal — clearing 4.5:1 on cream needs relative luminance
+ * <= ~0.17, clearing it on near-black needs >= ~0.22, and those do not overlap.
+ * So the bar is 3:1, WCAG's threshold for UI components and large text, which
+ * admits a band of mid-dark saturated colours. Every accent below clears 3:1
+ * against BOTH reference backgrounds, verified in theme-adaptive-colors.test.ts —
+ * so a colour that only works on dark cannot be added without failing the build.
+ *
+ * Where we own a badge's background we also own its ink, so `ink` is plain white
+ * and its contrast is deterministic rather than a function of the user's theme.
+ * That is why badge ink is not slot 0 or the terminal background: on a light
+ * theme, terminal-background ink on a yellow chip is unreadable.
+ */
+
+/** Reference backgrounds every accent is measured against. */
+export const CONTRAST_REFERENCE = {
+	light: "#FAFAD2",
+	dark: "#1C1C1E",
+} as const;
+
+/**
+ * The vivid set. Ratios are (on light / on dark), measured — see the test.
+ * Hues for the three scopes are deliberately far apart (blue / green / amber)
+ * because they appear as single-character squares, where a subtle hue shift is
+ * not readable at all.
+ */
+export const brand = {
+	accent: "#9333EA", // 5.04 / 3.16 — brand purple
+	link: "#2563EB", // 4.84 / 3.29
+	info: "#0E7490", // 5.02 / 3.18 — teal
+	success: "#15803D", // 4.70 / 3.39
+	warning: "#B45309", // 4.70 / 3.39 — amber
+	danger: "#DC2626", // 4.52 / 3.52
+	muted: "#6B7280", // 4.53 / 3.52 — de-emphasis, still legible on both
+	/** Ink on OUR badges. We own both sides, so contrast is deterministic. */
+	ink: "#FFFFFF",
+	/**
+	 * De-emphasised ink on the SELECTION fill, and nowhere else.
+	 *
+	 * Measured on a screenshot: `muted` (#6B7280) on the selection purple is
+	 * 1.11:1, `warning` 1.07:1, `danger` 1.11:1 — every meta tone was invisible
+	 * the moment its row was selected, and `(default)` on the Models screen
+	 * disappeared entirely. The page-level greys cannot help here: they are
+	 * chosen to sit between a cream and a near-black terminal, and the selection
+	 * is neither.
+	 *
+	 * 3.64:1 on the selection fill, and 1.48:1 against `ink` — far enough from
+	 * white to still read as secondary. Like `ink`, it is measured against a fill
+	 * WE paint rather than against the terminal, so it is exempt from the
+	 * both-backgrounds rule the accents above obey.
+	 */
+	selectionDim: "#D4D4D8",
+} as const;
+
+/** Any colour a component may hand to a JSX colour prop. */
+export type UiColor = string | RGBA;
+
+/** The terminal's own foreground — the only honest "normal text" colour. */
+const fg = () => RGBA.defaultForeground();
+
+/** The terminal's own background — for surfaces, never for ink. */
+const bg = () => RGBA.defaultBackground();
+
+export const theme = {
+	colors: {
+		/** Adaptive by rule 2 — never make this one of ours. */
+		text: fg(),
+		muted: brand.muted,
+		/** Same grey as `muted`; a third level should come from layout, not colour. */
+		dim: brand.muted,
+		border: brand.muted,
+		link: brand.link,
+		accent: brand.accent,
+		/** Low-key brand tint for bylines — readable, deliberately not attention-grabbing. */
+		byline: brand.accent,
+		success: brand.success,
+		warning: brand.warning,
+		danger: brand.danger,
+		info: brand.info,
+	},
+
+	/**
+	 * The selected row owns the colour channel.
+	 *
+	 * A row's normal palette is chosen against the TERMINAL's background; on the
+	 * selection fill none of it clears even 1.2:1. So a selected row has exactly
+	 * two inks — `fg` for what it is saying, `dim` for what it is saying quietly —
+	 * and any tone a row would otherwise carry is surrendered while it is
+	 * selected. The words survive; the hue does not, and cannot.
+	 */
+	selection: {
+		bg: brand.accent,
+		fg: brand.ink,
+		dim: brand.selectionDim,
+	},
+
+	/** Blue / green / amber: the widest hue separation available, because these
+	 *  render as one-character squares where a subtle shift reads as noise. */
+	scopes: {
+		user: brand.link,
+		project: brand.success,
+		local: brand.warning,
+	},
+
+	/** Badge colours. `fg` is the ink ON the block; `badgeFg` is the same hue used
+	 *  as ink on the normal background instead. */
+	category: {
+		purple: { bg: brand.accent, fg: brand.ink, badgeFg: brand.accent },
+		green: { bg: brand.success, fg: brand.ink, badgeFg: brand.success },
+		teal: { bg: brand.info, fg: brand.ink, badgeFg: brand.info },
+		yellow: { bg: brand.warning, fg: brand.ink, badgeFg: brand.warning },
+		gray: { bg: brand.muted, fg: brand.ink, badgeFg: brand.muted },
+		red: { bg: brand.danger, fg: brand.ink, badgeFg: brand.danger },
+	},
+
+	meta: {
+		muted: brand.muted,
+		warning: brand.warning,
+		success: brand.success,
+		danger: brand.danger,
+	},
+
+	/**
+	 * Footer key chips. A vivid block with white ink, because the point of a chip
+	 * is to read as a pressable key at a glance — the previous neutral-grey chip
+	 * melted into a light page. Dark slates were measured and rejected: they clear
+	 * 3:1 on cream but drop to ~2.2 on a dark terminal, i.e. an invisible block.
+	 */
+	hints: {
+		defaultBg: brand.accent,
+		primaryBg: brand.info,
+		dangerBg: brand.danger,
+		fg: brand.ink,
+	},
+
+	/** Panels and modals sit on the terminal's own background and are separated by
+	 *  their border, never by an absolute fill that fights the user's theme. */
+	surface: {
+		bg: bg(),
+		border: brand.muted,
+	},
+
+	spacing: {
+		rowIndent: 1,
+		sectionGap: 1,
+		panelPadding: 1,
+	},
+} as const;
+
+export { fg as defaultFg, bg as defaultBg };

package/src/utils/clipboard.ts

@@ -0,0 +1,58 @@
+import { execSync } from "node:child_process";
+
+/**
+ * Write text to the system clipboard.
+ * macOS: uses pbcopy
+ * Linux: uses xclip
+ * Throws ClipboardUnavailableError if no clipboard tool is available.
+ */
+export async function writeClipboard(text: string): Promise<void> {
+	if (process.platform === "darwin") {
+		execSync("pbcopy", { input: text });
+	} else if (process.platform === "linux") {
+		execSync("xclip -selection clipboard", { input: text });
+	} else {
+		throw new ClipboardUnavailableError(
+			`Clipboard not supported on platform: ${process.platform}`,
+		);
+	}
+}
+
+/**
+ * Read text from the system clipboard.
+ * macOS: uses pbpaste
+ * Linux: uses xclip
+ * Throws ClipboardUnavailableError if no clipboard tool is available.
+ */
+export async function readClipboard(): Promise<string> {
+	if (process.platform === "darwin") {
+		return execSync("pbpaste").toString();
+	}
+	if (process.platform === "linux") {
+		return execSync("xclip -selection clipboard -o").toString();
+	}
+	throw new ClipboardUnavailableError(
+		`Clipboard not supported on platform: ${process.platform}`,
+	);
+}
+
+export class ClipboardUnavailableError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ClipboardUnavailableError";
+	}
+}
+
+/** Check if clipboard operations are available on this platform/system */
+export function isClipboardAvailable(): boolean {
+	if (process.platform === "darwin") return true;
+	if (process.platform === "linux") {
+		try {
+			execSync("which xclip", { stdio: "ignore" });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	return false;
+}

package/src/utils/command-utils.ts

@@ -0,0 +1,149 @@
+import { constants, accessSync, statSync } from "node:fs";
+import { access, realpath } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * A command as an executable plus its already-separated arguments.
+ *
+ * The alternative — a single string handed to `/bin/sh` — has cost this
+ * codebase twice, in two different ways, and both were shipped rather than
+ * hypothetical:
+ *
+ *  1. **A word the shell could not resolve.** `pip install <pkg>` died with
+ *     `/bin/sh: pip: command not found` on machines where `pip` is only an
+ *     interactive-zsh alias. `services/toolchain.ts` fixed *which word* gets
+ *     emitted; it could not fix that the words are re-parsed at spawn time.
+ *  2. **Package names are re-parsed as shell syntax.** The builders are fed
+ *     `bin.package` / `bin.formula` / `bin.module`, which come from
+ *     `.claude/profiles.json` and from plugin `requires.bin` — hand-authored,
+ *     committed by teammates, fetched from marketplaces. Under `shell: true`
+ *     those go through word-splitting and `$(…)` expansion. Today's catalogue is
+ *     benign; the surface is not, and nothing checks it.
+ *
+ * As argv there is no shell, so a package name is one token no matter what
+ * characters it contains, and `cmd` must name a real executable rather than
+ * anything PATH-plus-a-profile might have meant.
+ *
+ * `services/plugin-setup.ts` arrived at this same shape independently for the
+ * MCP dependency installer. This is the codebase agreeing with itself.
+ */
+export interface Command {
+	readonly cmd: string;
+	readonly args: readonly string[];
+}
+
+/**
+ * Characters that need no quoting in any POSIX shell.
+ *
+ * Deliberately conservative, and the reason {@link formatCommand} is display-
+ * neutral: every token magus actually builds — `@anthropic-ai/claude-code`,
+ * `claudish@1.2.0`, `aider==0.1`, `github.com/x/t@latest`, `--upgrade` — is
+ * made only of these, so quoting never fires for real input and the rendered
+ * string is byte-identical to the one this codebase printed before commands
+ * became argv. `doctor-bins.test.ts` is the gate on that claim.
+ */
+const SHELL_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+
+/**
+ * Render a {@link Command} as the shell line a human would type.
+ *
+ * FOR DISPLAY ONLY. Nothing may feed this back to a shell — that would undo the
+ * whole point of carrying argv. It exists so `doctor` can print "run: brew
+ * install tmux" and the updater can show what it is about to do.
+ *
+ * A token outside {@link SHELL_SAFE} is single-quoted, with `'` closed,
+ * escaped and reopened (`'\''`) — the only POSIX-portable escape, since single
+ * quotes have no escape character inside them. An empty token quotes too:
+ * unquoted it would vanish, which would misrepresent the argv it came from.
+ */
+export function formatCommand(c: Command): string {
+	return [c.cmd, ...c.args].map(quoteToken).join(" ");
+}
+
+function quoteToken(token: string): string {
+	if (SHELL_SAFE.test(token)) return token;
+	return `'${token.replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * Check if a command exists in PATH.
+ *
+ * Async only for its callers' sake — it spawns nothing. This used to run
+ * `execFileAsync("which", [command])`, a real `which(1)` process with no
+ * timeout, on every one of its dozen call sites. Answering "is bun on PATH?"
+ * does not need a process, and under load that process is what stalls:
+ * `detectToolchains` calls this per toolchain, and in a 103-file parallel test
+ * run the spawn queue backed up until the test failed at **20,007 ms** — after
+ * the per-test timeout had already been raised from 5s to 20s to accommodate
+ * the earlier 5s failures. Raising the limit moved the goalposts; removing the
+ * spawn removes the stall.
+ *
+ * {@link whichSync} is also STRICTER than `which(1)`, which is a bonus rather
+ * than a risk: it stats the candidate and checks the execute bit, so a dangling
+ * symlink answers null here instead of reporting the link's own path. That is
+ * the exact failure {@link resolveExecutable} was written to catch afterwards.
+ *
+ * @param command - Command name to check, or an explicit path
+ * @returns Path to command if found, null otherwise
+ */
+export async function which(command: string): Promise<string | null> {
+	return whichSync(command);
+}
+
+/**
+ * Synchronous PATH lookup — walks `$PATH` rather than spawning `which(1)`.
+ *
+ * Synchronous on purpose. The installer-command builders in
+ * `services/toolchain.ts` are sync and used by printers; making them async just
+ * to answer "does this machine have uv?" would ripple through every caller.
+ *
+ * Node's `fs` is used rather than `Bun.which` so this needs no `@types/bun`,
+ * whose globals collide with `@types/node` in this project.
+ *
+ * Unlike {@link resolveExecutable} this does NOT follow symlinks to prove the
+ * target still exists — use it to pick between candidates, not to prove a
+ * binary works.
+ */
+export function whichSync(command: string): string | null {
+	// An explicit path is not a PATH lookup; honour it as given.
+	if (command.includes("/")) {
+		return isExecutableFile(command) ? command : null;
+	}
+	for (const dir of (process.env.PATH ?? "").split(":")) {
+		if (!dir) continue;
+		const candidate = join(dir, command);
+		if (isExecutableFile(candidate)) return candidate;
+	}
+	return null;
+}
+
+function isExecutableFile(p: string): boolean {
+	try {
+		if (!statSync(p).isFile()) return false;
+		accessSync(p, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Like {@link which}, but verifies the command actually RESOLVES and is
+ * executable — a dangling symlink (e.g. a stale npx-cache link) returns null.
+ * `which` alone reports the symlink's own path even when its target is gone,
+ * which is exactly how a plugin's binary can look "present" yet fail at runtime.
+ * @returns The real (symlink-resolved) executable path, or null.
+ */
+export async function resolveExecutable(
+	command: string,
+): Promise<string | null> {
+	const p = await which(command);
+	if (!p) return null;
+	try {
+		const real = await realpath(p); // follows symlinks; throws if dangling
+		await access(real, constants.X_OK); // must be executable
+		return real;
+	} catch {
+		return null; // dangling link or not executable
+	}
+}

package/src/utils/config-dir.ts

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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,
+ * any test that had not isolated its config dir began reading the operator's real
+ * cooldown file and fetching from their real marketplace clones. The suite went
+ * from 6s to 59s and started failing intermittently, because results depended on
+ * whether this particular machine happened to be rate-limited at that moment.
+ *
+ * A test that forgets to isolate should get nothing, not the developer's live
+ * state. Production is unaffected: NODE_ENV is not "test" there.
+ */
+
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * The Claude config directory, or null when a test has not chosen one.
+ *
+ * Callers that must always have a path (writing real user config) should use
+ * `requireClaudeConfigDir`. Callers holding regenerable state — caches — should
+ * treat null as "cache unavailable" and carry on.
+ */
+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");
+}
+
+/** The Claude config directory, falling back to `~/.claude` even under test. */
+export function requireClaudeConfigDir(): string {
+	return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+}

package/src/utils/file-locking.ts

@@ -0,0 +1,146 @@
+/**
+ * File locking utilities for concurrent write protection
+ *
+ * Prevents race conditions when multiple processes modify settings files
+ * Uses lock files for cross-platform compatibility
+ */
+
+import { existsSync } from "node:fs";
+import { mkdir, open } from "node:fs/promises";
+import type { FileHandle } from "node:fs/promises";
+import { dirname } from "node:path";
+
+/**
+ * Maximum time to wait for a lock (milliseconds)
+ */
+const LOCK_TIMEOUT_MS = 10000;
+
+/**
+ * Lock retry interval (milliseconds)
+ */
+const LOCK_RETRY_INTERVAL_MS = 100;
+
+/**
+ * Acquire exclusive lock on file and execute operation
+ * Uses lock files for cross-platform compatibility
+ *
+ * @param filePath - Path to file to lock
+ * @param operation - Async operation to execute with lock held
+ * @returns Result of the operation
+ * @throws Error if lock cannot be acquired within timeout
+ */
+export async function withFileLock<T>(
+	filePath: string,
+	operation: () => Promise<T>,
+): Promise<T> {
+	const lockPath = `${filePath}.lock`;
+	const lockDir = dirname(lockPath);
+
+	// Ensure lock directory exists
+	if (!existsSync(lockDir)) {
+		await mkdir(lockDir, { recursive: true });
+	}
+
+	const startTime = Date.now();
+	let fileHandle: FileHandle | null = null;
+
+	// Try to acquire lock with retries
+	while (Date.now() - startTime < LOCK_TIMEOUT_MS) {
+		try {
+			// Try to create lock file exclusively (fails if exists)
+			fileHandle = await open(lockPath, "wx");
+
+			// Write PID to lock file for debugging
+			await fileHandle.write(`${process.pid}\n${new Date().toISOString()}\n`);
+
+			break;
+		} catch (error: unknown) {
+			// Lock file exists, retry after interval
+			if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+				await new Promise((resolve) =>
+					setTimeout(resolve, LOCK_RETRY_INTERVAL_MS),
+				);
+				continue;
+			}
+			throw error;
+		}
+	}
+
+	if (fileHandle === null) {
+		throw new Error(
+			`Failed to acquire lock on ${filePath} after ${LOCK_TIMEOUT_MS}ms. ` +
+				`Another process may be holding the lock. Lock file: ${lockPath}`,
+		);
+	}
+
+	try {
+		// Execute operation with lock held
+		return await operation();
+	} finally {
+		// Release lock
+		try {
+			await fileHandle.close();
+			// Delete lock file
+			const fs = await import("node:fs/promises");
+			await fs.unlink(lockPath);
+		} catch (error) {
+			// Log error but don't throw - operation succeeded
+			console.error(`Warning: Failed to release lock ${lockPath}:`, error);
+		}
+	}
+}
+
+/**
+ * Check if file is currently locked
+ *
+ * @param filePath - Path to file to check
+ * @returns True if lock file exists
+ */
+export function isFileLocked(filePath: string): boolean {
+	const lockPath = `${filePath}.lock`;
+	return existsSync(lockPath);
+}
+
+/**
+ * Force remove lock file (use with caution)
+ * Only use if you're certain the lock is stale
+ *
+ * @param filePath - Path to file whose lock to remove
+ */
+export async function forceRemoveLock(filePath: string): Promise<void> {
+	const lockPath = `${filePath}.lock`;
+	try {
+		const fs = await import("node:fs/promises");
+		await fs.unlink(lockPath);
+	} catch (error: unknown) {
+		// Ignore ENOENT (lock doesn't exist)
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+			throw error;
+		}
+	}
+}
+
+/**
+ * Get information about current lock
+ *
+ * @param filePath - Path to file to check
+ * @returns Lock info or null if not locked
+ */
+export async function getLockInfo(
+	filePath: string,
+): Promise<{ pid: string; timestamp: string } | null> {
+	const lockPath = `${filePath}.lock`;
+
+	if (!existsSync(lockPath)) {
+		return null;
+	}
+
+	try {
+		const fs = await import("node:fs/promises");
+		const content = await fs.readFile(lockPath, "utf-8");
+		const [pid, timestamp] = content.trim().split("\n");
+		return { pid, timestamp };
+	} catch (error) {
+		return null;
+	}
+}