magus-cli 0.0.0-placeholder → 7.1.0

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();
+		});
+	});
+}

package/src/utils/run.ts

@@ -0,0 +1,67 @@
+/**
+ * Running an installer, with the shell split out from the argv.
+ *
+ * Lives in `utils/` rather than `cli/prompt.ts` because the update engine needs
+ * it and a service must not import from the CLI layer — `cli/` and `ui/` are
+ * sibling front ends over `services/`, and an arrow from a service back up into
+ * one of them is how the two front ends ended up with different update logic in
+ * the first place.
+ *
+ * Both functions live in ONE file on purpose: {@link runShellScript}'s doc only
+ * makes sense next to {@link runCommand}, because most of what it has to say is
+ * "you almost certainly want the other one".
+ */
+
+import { spawn } from "node:child_process";
+import type { Command } from "./command-utils.js";
+
+/**
+ * Run a built command as argv, streaming its output; true on exit 0.
+ *
+ * **This is the one every installer uses.** No `shell` option, so:
+ *
+ *  - `cmd` is resolved on PATH as an executable. There is no profile to source
+ *    and therefore no way for a shell alias to appear to work — the reason the
+ *    shipped `pip install` bug could exist at all was that `/bin/sh` was asked
+ *    to resolve a word that only interactive zsh knew.
+ *  - Every argument stays exactly one argument. Package names reach here from
+ *    `.claude/profiles.json` and plugin `requires.bin` — hand-authored data
+ *    committed by teammates and fetched from marketplaces — and under a shell a
+ *    space or a `$(…)` in one of them would have been executed. Nothing
+ *    validates those names, and after this nothing has to.
+ *
+ * stdio is inherited: the installer owns the terminal while it runs, which is
+ * what makes brew's and bun's own progress output visible. A caller painting an
+ * animated region must pause it around this (see `ApplyReporter.detach`).
+ */
+export async function runCommand(c: Command): Promise<boolean> {
+	return new Promise((resolve) => {
+		const child = spawn(c.cmd, [...c.args], { stdio: "inherit" });
+		child.on("exit", (code) => resolve(code === 0));
+		child.on("error", () => resolve(false));
+	});
+}
+
+/**
+ * Run a shell SCRIPT through `/bin/sh`, streaming its output; true on exit 0.
+ *
+ * **Not for installer commands — use {@link runCommand}.** This exists for
+ * exactly one input: the values of `TOOLCHAIN_BOOTSTRAP`, which are the
+ * upstream-published one-liners for bun and Homebrew. Those genuinely are shell
+ * text — one contains a pipe, the other a command substitution — so they cannot
+ * be expressed as argv without wrapping them in a fake `/bin/sh -c` at the one
+ * place where a shell is actually correct.
+ *
+ * The distinction is who wrote the string. A bootstrap line is a constant in
+ * this repo, copied from bun.sh and brew.sh. An installer command is assembled
+ * from names that arrive with a profile. Passing the second kind here is the
+ * defect that motivated splitting the two, so
+ * `src/__tests__/shell-script-callers.test.ts` pins the caller set to one file.
+ */
+export async function runShellScript(script: string): Promise<boolean> {
+	return new Promise((resolve) => {
+		const child = spawn(script, { stdio: "inherit", shell: true });
+		child.on("exit", (code) => resolve(code === 0));
+		child.on("error", () => resolve(false));
+	});
+}

package/src/utils/string-utils.ts

@@ -0,0 +1,88 @@
+/**
+ * Shared string utilities for magus
+ */
+
+/**
+ * Format marketplace name for display
+ * e.g., "magus" -> "Magus"
+ */
+export function formatMarketplaceName(name: string): string {
+	return name
+		.split(/[-_]/)
+		.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+		.join(" ");
+}
+
+/**
+ * Validate GitHub repository format (org/repo)
+ * Prevents SSRF via malicious repo strings
+ */
+export function isValidGitHubRepo(repo: string): boolean {
+	if (!repo || typeof repo !== "string") {
+		return false;
+	}
+
+	// Must match GitHub username/repo format
+	// Username: alphanumeric, hyphens (no consecutive, not start/end)
+	// Repo: alphanumeric, hyphens, underscores, dots
+	const GITHUB_REPO_PATTERN =
+		/^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]\/[a-zA-Z0-9_.-]+$/;
+
+	// Allow single-char usernames too
+	const GITHUB_REPO_PATTERN_SHORT = /^[a-zA-Z0-9]\/[a-zA-Z0-9_.-]+$/;
+
+	if (
+		!GITHUB_REPO_PATTERN.test(repo) &&
+		!GITHUB_REPO_PATTERN_SHORT.test(repo)
+	) {
+		return false;
+	}
+
+	// Blocklist suspicious patterns
+	const BLOCKLIST = [
+		/\.\./, // Path traversal
+		/@/, // URL authority injection
+		/:/, // Port specification
+		/\s/, // Whitespace
+		/%/, // URL encoding
+		/\\/, // Backslash
+	];
+
+	return !BLOCKLIST.some((pattern) => pattern.test(repo));
+}
+
+/**
+ * Parse plugin ID into components
+ * Format: pluginName@marketplaceName
+ */
+export interface ParsedPluginId {
+	pluginName: string;
+	marketplace: string;
+	raw: string;
+}
+
+export function parsePluginId(pluginId: string): ParsedPluginId | null {
+	if (!pluginId || typeof pluginId !== "string") {
+		return null;
+	}
+
+	const trimmed = pluginId.trim();
+	const atIndex = trimmed.lastIndexOf("@");
+
+	if (atIndex <= 0) {
+		return null;
+	}
+
+	const pluginName = trimmed.slice(0, atIndex).trim();
+	const marketplace = trimmed.slice(atIndex + 1).trim();
+
+	if (!pluginName || !marketplace) {
+		return null;
+	}
+
+	return {
+		pluginName,
+		marketplace,
+		raw: trimmed,
+	};
+}