magus-cli 0.0.0-placeholder → 7.0.0

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,144 @@
+import { execFile } from "node:child_process";
+import { constants, accessSync, statSync } from "node:fs";
+import { access, realpath } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * 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
+ * Uses execFile (not exec) to avoid shell injection vulnerabilities
+ * @param command - Command name to check
+ * @returns Path to command if found, null otherwise
+ */
+export async function which(command: string): Promise<string | null> {
+	try {
+		// Use execFile with argument array to prevent command injection
+		const { stdout } = await execFileAsync("which", [command]);
+		return stdout.trim() || null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * 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;
+	}
+}

package/src/utils/fuzzy-search.ts

@@ -0,0 +1,138 @@
+/**
+ * Simple fuzzy search utility for filtering lists
+ * Uses a scoring algorithm that rewards:
+ * - Consecutive character matches
+ * - Matches at word boundaries
+ * - Matches at start of string
+ */
+
+export interface FuzzyMatch<T> {
+	item: T;
+	score: number;
+	matches: number[]; // indices of matched characters
+}
+
+/**
+ * Calculate fuzzy match score for a query against a target string
+ * Returns null if no match, otherwise returns score and match indices
+ */
+export function fuzzyMatch(
+	query: string,
+	target: string,
+): { score: number; matches: number[] } | null {
+	if (!query) return { score: 1, matches: [] };
+
+	const queryLower = query.toLowerCase();
+	const targetLower = target.toLowerCase();
+
+	let queryIdx = 0;
+	let score = 0;
+	const matches: number[] = [];
+	let prevMatchIdx = -1;
+
+	for (let i = 0; i < targetLower.length && queryIdx < queryLower.length; i++) {
+		if (targetLower[i] === queryLower[queryIdx]) {
+			matches.push(i);
+
+			// Bonus for consecutive matches
+			if (prevMatchIdx === i - 1) {
+				score += 5;
+			}
+
+			// Bonus for matching at word boundary
+			if (i === 0 || /[\s\-_.]/.test(target[i - 1])) {
+				score += 10;
+			}
+
+			// Bonus for matching at start
+			if (i === 0) {
+				score += 15;
+			}
+
+			// Base score for each match
+			score += 1;
+
+			prevMatchIdx = i;
+			queryIdx++;
+		}
+	}
+
+	// All query characters must be found
+	if (queryIdx !== queryLower.length) {
+		return null;
+	}
+
+	// Penalty for longer strings (prefer shorter, more precise matches)
+	score -= Math.floor(target.length / 10);
+
+	return { score, matches };
+}
+
+/**
+ * Filter and sort items by fuzzy match score
+ */
+export function fuzzyFilter<T>(
+	items: T[],
+	query: string,
+	getText: (item: T) => string,
+): FuzzyMatch<T>[] {
+	if (!query.trim()) {
+		return items.map((item) => ({ item, score: 1, matches: [] }));
+	}
+
+	const results: FuzzyMatch<T>[] = [];
+
+	for (const item of items) {
+		const text = getText(item);
+		const match = fuzzyMatch(query, text);
+
+		if (match) {
+			results.push({
+				item,
+				score: match.score,
+				matches: match.matches,
+			});
+		}
+	}
+
+	// Sort by score descending
+	return results.sort((a, b) => b.score - a.score);
+}
+
+/**
+ * Highlight matched characters in a string
+ * Returns array of { text, highlighted } segments
+ */
+export function highlightMatches(
+	text: string,
+	matches: number[],
+): Array<{ text: string; highlighted: boolean }> {
+	if (matches.length === 0) {
+		return [{ text, highlighted: false }];
+	}
+
+	const matchSet = new Set(matches);
+	const segments: Array<{ text: string; highlighted: boolean }> = [];
+	let currentSegment = "";
+	let isHighlighted = matchSet.has(0);
+
+	for (let i = 0; i < text.length; i++) {
+		const shouldHighlight = matchSet.has(i);
+
+		if (shouldHighlight !== isHighlighted) {
+			if (currentSegment) {
+				segments.push({ text: currentSegment, highlighted: isHighlighted });
+			}
+			currentSegment = text[i];
+			isHighlighted = shouldHighlight;
+		} else {
+			currentSegment += text[i];
+		}
+	}
+
+	if (currentSegment) {
+		segments.push({ text: currentSegment, highlighted: isHighlighted });
+	}
+
+	return segments;
+}

package/src/utils/go-module.ts

@@ -0,0 +1,36 @@
+/**
+ * Go module path → installed binary name.
+ *
+ * `go install` names the binary after the last path element of the module
+ * path, EXCEPT when that element is a major-version suffix: the module
+ * `github.com/MadAppGang/tmux-mcp/v2` installs `tmux-mcp`, not `v2`. Taking a
+ * plain basename therefore points every later check at a binary that never
+ * exists — presence probes fail, so the module is reinstalled on every run,
+ * doctor reports it missing, and the pin comparison never runs at all.
+ *
+ * Only the Go rule lives here. npm and cargo share the `name@version` syntax
+ * but not the suffix convention — an npm scoped package can legitimately be
+ * called `@scope/v2` — so this must not be folded into the generic spec parser.
+ */
+
+/**
+ * Trailing major-version suffix per the Go modules spec: `/vN` with N >= 2.
+ * Anchored to the END of the path with nothing after `vN`, so a segment that
+ * merely starts with "v2" (`github.com/x/v2tool`) is a real name, not a suffix.
+ * v0 and v1 are never written as a path suffix. The alternation, not a plain
+ * `[2-9][0-9]*`, because that shorthand rejects v10–v19 — a first digit of 1
+ * is only excluded when it is the ONLY digit.
+ */
+const MAJOR_VERSION_SUFFIX = /\/v(?:[2-9]|[1-9][0-9]+)$/;
+
+/**
+ * The binary `go install <modulePath>` produces.
+ *
+ * Takes the MODULE PATH — the part before any `@version` — so callers that
+ * hold a full `path@version` spec split it first. An empty or single-segment
+ * input is returned unchanged.
+ */
+export function goBinaryName(modulePath: string): string {
+	const withoutSuffix = modulePath.replace(MAJOR_VERSION_SUFFIX, "");
+	return withoutSuffix.split("/").pop() || withoutSuffix;
+}

package/src/utils/open-file.ts

@@ -0,0 +1,84 @@
+/**
+ * Hand a file or URL to the operating system's default application.
+ *
+ * Why this exists rather than launching `$EDITOR`: magus owns the terminal.
+ * Suspending an OpenTUI app to give the TTY to a full-screen editor and then
+ * restoring raw mode, the alternate screen buffer and the cursor is a reliable
+ * way to leave the terminal wedged if anything goes wrong in between. Handing
+ * the path to the OS launches a separate process that never touches our TTY.
+ */
+
+import { spawn } from "node:child_process";
+
+export interface Opener {
+	command: string;
+	/** Arguments that precede the target path. */
+	args: string[];
+}
+
+/**
+ * The platform's "open this with whatever handles it" command.
+ *
+ * magus ships darwin-arm64, darwin-x64 and linux-x64, so macOS and Linux
+ * both have to work — the existing `open "${url}"` call in the Skills screen is
+ * macOS-only and silently does nothing on Linux.
+ */
+export function openerFor(platform: NodeJS.Platform): Opener {
+	if (platform === "darwin") return { command: "open", args: [] };
+	// `start` is a cmd.exe builtin, and its first quoted argument is the window
+	// title — hence the empty string, or a quoted path would be consumed as one.
+	if (platform === "win32")
+		return { command: "cmd", args: ["/c", "start", ""] };
+	return { command: "xdg-open", args: [] };
+}
+
+/**
+ * Open `target` in the default application, without blocking the TUI.
+ *
+ * The child is spawned WITHOUT a shell and the target is passed as its own
+ * argv entry, so a filename containing a space, quote or `$(…)` is opened
+ * rather than interpreted. Resolves once the process has been spawned, not
+ * when it exits — the viewer outlives us by design.
+ */
+export function openInDefaultApp(
+	target: string,
+	platform: NodeJS.Platform = process.platform,
+	/**
+	 * Test seam. The default is the platform's real opener; a test passes a
+	 * command that cannot exist, so the missing-opener path is exercised
+	 * deterministically on every OS — CI runners ship `xdg-open`, so "assume
+	 * the opener is absent" fails exactly there, and "spawn the real one"
+	 * launches applications on a build machine.
+	 */
+	opener: Opener = openerFor(platform),
+): Promise<void> {
+	const { command, args } = opener;
+
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		const child = spawn(command, [...args, target], {
+			detached: true,
+			stdio: "ignore",
+		});
+
+		child.once("error", (error: NodeJS.ErrnoException) => {
+			if (settled) return;
+			settled = true;
+			reject(
+				error.code === "ENOENT"
+					? new Error(
+							`No way to open files here — "${command}" is not on PATH.`,
+						)
+					: error,
+			);
+		});
+
+		child.once("spawn", () => {
+			if (settled) return;
+			settled = true;
+			// Detach so magus exiting does not take the editor with it.
+			child.unref();
+			resolve();
+		});
+	});
+}