magus-cli 0.0.0-placeholder → 7.0.0

package/src/cli/upgrade.ts

@@ -0,0 +1,97 @@
+/**
+ * `magus upgrade` — self-update.
+ *
+ * This is what `magus update` used to do. `update` now means what it means
+ * in every package manager — bring THIS PROJECT's dependencies up to date —
+ * and advancing the tool itself moved here.
+ *
+ * Detects magus installs across bun + npm global, warns on duplicates
+ * (active vs shadowed), then re-installs `magus@latest` with whichever
+ * package manager owns the active binary. Resolves with the child's exit code.
+ */
+
+import { spawn } from "node:child_process";
+import { constants } from "node:os";
+
+export async function runUpgradeCommand(): Promise<number> {
+	const { execSync } = await import("node:child_process");
+	const { existsSync } = await import("node:fs");
+
+	// Detect all installations of magus across package managers
+	const installations: Array<{ manager: "bun" | "npm"; path: string }> = [];
+
+	// Check bun global
+	try {
+		const bunGlobalBin = execSync("bun pm -g bin", {
+			encoding: "utf-8",
+			timeout: 5000,
+		}).trim();
+		const bunPath = `${bunGlobalBin}/magus`;
+		if (existsSync(bunPath))
+			installations.push({ manager: "bun", path: bunPath });
+	} catch {
+		// bun not installed or no global magus
+	}
+
+	// Check npm global
+	try {
+		const npmPrefix = execSync("npm prefix -g", {
+			encoding: "utf-8",
+			timeout: 5000,
+		}).trim();
+		const npmPath = `${npmPrefix}/bin/magus`;
+		if (existsSync(npmPath))
+			installations.push({ manager: "npm", path: npmPath });
+	} catch {
+		// npm not installed or no global magus
+	}
+
+	// Warn about duplicate installations
+	if (installations.length > 1) {
+		const activePath = execSync("which magus", {
+			encoding: "utf-8",
+			timeout: 5000,
+		}).trim();
+
+		console.log("⚠ magus is installed via multiple package managers:\n");
+		for (const inst of installations) {
+			const tag = inst.path === activePath ? " (active)" : " (shadowed)";
+			console.log(`  ${inst.manager}: ${inst.path}${tag}`);
+		}
+		console.log("\nTo fix, keep one and remove the other:");
+		for (const inst of installations) {
+			console.log(`  ${inst.manager} uninstall -g magus`);
+		}
+		console.log();
+	}
+
+	// Determine which package manager to use for the update
+	let usesBun = false;
+	try {
+		const magusPath = execSync("which magus", {
+			encoding: "utf-8",
+		}).trim();
+		usesBun = magusPath.includes(".bun") || magusPath.includes("bun/bin");
+	} catch {
+		// If which fails, default to npm
+	}
+
+	const pkgManager = usesBun ? "bun" : "npm";
+	console.log(`Updating magus using ${pkgManager}...`);
+
+	const installArgs = ["install", "-g", "magus@latest"];
+
+	return new Promise<number>((resolve) => {
+		const proc = spawn(pkgManager, installArgs, {
+			stdio: "inherit",
+			shell: false, // Avoid shell for security (fixes DEP0190 warning)
+		});
+		// `code ?? 0` is the same defect 6.8.1 removed from bin/magus.js: a
+		// package manager killed by a signal delivers code null, and reporting
+		// that upgrade as a success is the worst answer available.
+		proc.on("exit", (code, signal) =>
+			resolve(code ?? (signal ? 128 + (constants.signals[signal] ?? 0) : 1)),
+		);
+		proc.on("error", () => resolve(1));
+	});
+}

package/src/data/alias-flags.ts

@@ -0,0 +1,301 @@
+/**
+ * Catalog of `claude` CLI flags that the Alias tab can compose into a managed
+ * shell alias. Verified against `claude --help` output and binary string scan
+ * of the shipped Claude Code 2.1.x binary.
+ *
+ * The catalog drives both the UI editor for each flag and the renderer that
+ * emits the final `alias claude='claude …'` string per shell.
+ */
+
+export type FlagKind =
+	/** On/off. AliasFlagState: { enabled: boolean } */
+	| "boolean"
+	/** Three states: unset / on / off. Used for `--chrome` vs `--no-chrome`. */
+	| "tri-state"
+	/** Single value from a fixed list. AliasFlagState: { enabled, value }. */
+	| "select"
+	/** Free-form string. AliasFlagState: { enabled, value }. */
+	| "text"
+	/** Optional free-form string (flag works with or without a value). */
+	| "optional-text"
+	/** Repeatable list of strings. AliasFlagState: { enabled, values }. */
+	| "text-list"
+	/**
+	 * Picklist of common tokens + free-form custom tokens, joined with commas.
+	 * AliasFlagState: { enabled, picked: string[], custom: string[] }.
+	 * Used for `--debug` because Claude Code's category set is dynamic.
+	 */
+	| "multi-with-custom";
+
+export interface FlagSelectOption {
+	label: string;
+	value: string;
+}
+
+export interface AliasFlag {
+	/** Stable identifier; used as JSON key in `~/.claude/magus-alias.json`. */
+	id: string;
+	/** Human label shown in the UI list. */
+	label: string;
+	/**
+	 * The CLI flag as it appears on the command line. For tri-state, this is the
+	 * "on" form (e.g. `--chrome`); the "off" form is in `triStateOff`.
+	 */
+	flag: string;
+	/** Optional short flag (e.g. `-d` for `--debug`). Not currently rendered. */
+	shortFlag?: string;
+	kind: FlagKind;
+	/** One-line description shown in the detail panel. */
+	description: string;
+	/** Allowed values for `kind: "select"`. */
+	options?: FlagSelectOption[];
+	/** "Off" form for tri-state flags (e.g. `--no-chrome`). */
+	triStateOff?: string;
+	/** Picklist tokens for `kind: "multi-with-custom"`. */
+	picklist?: string[];
+	/** Default seed values for `text-list` and `multi-with-custom`. */
+	defaultValues?: string[];
+	/**
+	 * Validation key. The renderer / UI consult this to grey out conflicting
+	 * fields. Two flags with the same `xorGroup` are mutually exclusive.
+	 */
+	xorGroup?: string;
+	/**
+	 * The flag is only valid when another flag (by id) is enabled.
+	 * UI greys out and shows "requires --xxx".
+	 */
+	requires?: string;
+	/**
+	 * If true, the value supports `{token}` placeholders that expand at shell
+	 * eval time (not at write time). The renderer emits the value as a mix of
+	 * literal segments and shell substitution segments instead of one quoted
+	 * token. See `TEMPLATE_TOKENS` for the supported placeholder set.
+	 */
+	templated?: boolean;
+	/** UI grouping; rendered as section headers in the list. */
+	group: FlagGroup;
+}
+
+/**
+ * Tokens supported in `templated: true` flag values. Description text is
+ * shown to the user; the actual shell-substitution code lives in the writer
+ * because it needs per-shell variants.
+ *
+ * Intentionally excludes `{hash}` for v1 — its only portable form is
+ * `od -An -N4 -tx1 /dev/urandom | tr -d ' \n'`, which looks frightening in a
+ * shell rc file. Users who want randomness can pair this prefix with bare
+ * `--remote-control` (which already auto-generates a unique suffix).
+ */
+export const TEMPLATE_TOKENS: Array<{ token: string; description: string }> = [
+	{ token: "{folder}", description: "current directory's basename" },
+	{ token: "{day}", description: "day of month, zero-padded (01-31)" },
+	{ token: "{month}", description: "month, zero-padded (01-12)" },
+	{ token: "{year}", description: "4-digit year" },
+];
+
+export type FlagGroup =
+	| "danger"
+	| "session"
+	| "context"
+	| "channels"
+	| "debug"
+	| "integration"
+	| "worktree";
+
+export const FLAG_GROUPS: Array<{ id: FlagGroup; label: string }> = [
+	{ id: "danger", label: "Permissions" },
+	{ id: "session", label: "Session" },
+	{ id: "context", label: "Context" },
+	{ id: "channels", label: "Development channels" },
+	{ id: "debug", label: "Debug" },
+	{ id: "integration", label: "Integrations" },
+	{ id: "worktree", label: "Worktree" },
+];
+
+export const ALIAS_FLAGS: AliasFlag[] = [
+	{
+		id: "dangerously-skip-permissions",
+		label: "Skip permission checks",
+		flag: "--dangerously-skip-permissions",
+		kind: "boolean",
+		group: "danger",
+		description:
+			"Bypass all permission checks. Recommended only for sandboxes with no internet access.",
+	},
+	{
+		id: "allow-dangerously-skip-permissions",
+		label: "Allow skip-permissions opt-in",
+		flag: "--allow-dangerously-skip-permissions",
+		kind: "boolean",
+		group: "danger",
+		description:
+			"Enable the skip-permissions option without making it the default.",
+	},
+	{
+		id: "remote-control",
+		label: "Remote control",
+		flag: "--remote-control",
+		kind: "boolean",
+		group: "session",
+		description:
+			"Start an interactive session with Remote Control enabled. Claude Code auto-generates a unique session name; use --remote-control-session-name-prefix to customize it.",
+	},
+	{
+		id: "remote-control-session-name-prefix",
+		label: "Remote control name prefix",
+		flag: "--remote-control-session-name-prefix",
+		kind: "text",
+		templated: true,
+		group: "session",
+		description:
+			"Prefix for auto-generated Remote Control session names. Default: hostname. Supports template tokens that expand on each shell invocation: {folder} (basename of $PWD), {day}, {month}, {year}. Example: dev-{folder}-{day} → dev-myproject-15.",
+	},
+	{
+		id: "ide",
+		label: "Auto-connect to IDE",
+		flag: "--ide",
+		kind: "boolean",
+		group: "integration",
+		description:
+			"Automatically connect to IDE on startup if exactly one valid IDE is available.",
+	},
+	{
+		id: "chrome",
+		label: "Chrome integration",
+		flag: "--chrome",
+		triStateOff: "--no-chrome",
+		kind: "tri-state",
+		group: "integration",
+		description:
+			"Enable or disable Claude in Chrome integration. Unset leaves the project default in place.",
+	},
+	{
+		id: "effort",
+		label: "Effort level",
+		flag: "--effort",
+		kind: "select",
+		group: "session",
+		description: "Effort level for the current session.",
+		options: [
+			{ label: "low", value: "low" },
+			{ label: "medium", value: "medium" },
+			{ label: "high", value: "high" },
+			{ label: "xhigh", value: "xhigh" },
+			{ label: "max", value: "max" },
+		],
+	},
+	{
+		id: "system-prompt",
+		label: "System prompt",
+		flag: "--system-prompt",
+		kind: "text",
+		group: "context",
+		xorGroup: "system-prompt",
+		description:
+			"System prompt text to use for the session. Mutually exclusive with --system-prompt-file.",
+	},
+	{
+		id: "system-prompt-file",
+		label: "System prompt file",
+		flag: "--system-prompt-file",
+		kind: "text",
+		group: "context",
+		xorGroup: "system-prompt",
+		description:
+			"Path to a file whose contents replace the default system prompt. Mutually exclusive with --system-prompt.",
+	},
+	{
+		id: "append-system-prompt",
+		label: "Append system prompt",
+		flag: "--append-system-prompt",
+		kind: "text",
+		group: "context",
+		description:
+			"Text appended to the default system prompt. Composes with --system-prompt.",
+	},
+	{
+		id: "append-system-prompt-file",
+		label: "Append system prompt file",
+		flag: "--append-system-prompt-file",
+		kind: "text",
+		group: "context",
+		description:
+			"Path to a file whose contents are appended to the default system prompt.",
+	},
+	{
+		id: "channels",
+		label: "Channels (approved)",
+		flag: "--channels",
+		kind: "text-list",
+		group: "channels",
+		description:
+			"Approved channel plugins/MCP servers to run this session (the allowlist). Channels derived from --dangerously-load appear in a separate section here and are unioned in on write; add your own approved channels on top.",
+		defaultValues: [],
+	},
+	{
+		id: "dangerously-load-development-channels",
+		label: "Load development channels",
+		flag: "--dangerously-load-development-channels",
+		kind: "text-list",
+		group: "channels",
+		description:
+			"Sideload development channels not on the approved allowlist (local dev only). Also shown under --channels and unioned into it on write. Default seed: claudish (the only magus plugin currently shipping channels).",
+		defaultValues: ["plugin:claudish@magus"],
+	},
+	{
+		id: "debug",
+		label: "Debug categories",
+		flag: "--debug",
+		shortFlag: "-d",
+		kind: "multi-with-custom",
+		group: "debug",
+		description:
+			"Enable debug mode with optional category filter. Pick from common categories or add custom tokens (including negations like !file).",
+		picklist: [
+			"api",
+			"hooks",
+			"mcp",
+			"tools",
+			"plugins",
+			"skills",
+			"settings",
+			"permissions",
+			"auth",
+			"cache",
+			"statsig",
+			"file",
+			"1p",
+		],
+		defaultValues: [],
+	},
+	{
+		id: "worktree",
+		label: "Use worktree",
+		flag: "--worktree",
+		kind: "boolean",
+		group: "worktree",
+		description:
+			"Create a git worktree for the session. Prerequisite for --tmux.",
+	},
+	{
+		id: "tmux",
+		label: "tmux session",
+		flag: "--tmux",
+		kind: "select",
+		group: "worktree",
+		requires: "worktree",
+		description:
+			"Create a tmux session for the worktree. Requires --worktree. iTerm2 native panes when available; classic for traditional tmux.",
+		options: [
+			{ label: "auto (iTerm2 native)", value: "" },
+			{ label: "classic", value: "classic" },
+		],
+	},
+];
+
+/** Look up a flag by id. Throws if missing — keeps callers honest. */
+export function getFlagById(id: string): AliasFlag {
+	const f = ALIAS_FLAGS.find((flag) => flag.id === id);
+	if (!f) throw new Error(`Unknown alias flag id: ${id}`);
+	return f;
+}

package/src/data/cli-tools.ts

@@ -0,0 +1,146 @@
+import type { BinInstaller } from "../types/index.js";
+
+/**
+ * A CLI tool magus can install, check and update.
+ *
+ * There is deliberately NO `installCommand` field. Entries used to carry one
+ * alongside `packageManager` + `packageName`, which describe the same thing —
+ * so the two could disagree, and did: `aider` declared
+ * `packageName: "aider-chat"` while its `installCommand` installed
+ * `aider-install`, and the version check queried the former. The command is
+ * derived by `services/cli-tool-commands.ts` instead, which also means a
+ * catalogue entry can no longer smuggle shell syntax (that same entry's command
+ * was a `&&` chain) into something that gets executed.
+ */
+export interface CliTool {
+	name: string;
+	displayName: string;
+	description: string;
+	checkCommand: string;
+	website: string;
+	category: "ai-coding" | "utility";
+	/**
+	 * Reuses `BinInstaller` rather than restating its members, so the
+	 * correspondence with the resolver in `services/toolchain.ts` — which is
+	 * what turns this field into an actual command — is a compile-time fact.
+	 */
+	packageManager: BinInstaller;
+	packageName: string;
+}
+
+export const cliTools: CliTool[] = [
+	{
+		name: "magus",
+		displayName: "magus",
+		description:
+			"TUI tool for managing Claude Code plugins, MCPs, and configuration",
+		checkCommand: "magus --version",
+		website: "https://github.com/MadAppGang/magus/tree/main/tools/magus",
+		category: "ai-coding",
+		packageManager: "bun",
+		packageName: "magus",
+	},
+	{
+		name: "mnemex",
+		displayName: "Mnemex",
+		description:
+			"AST-aware code search with PageRank, callers/callees, and semantic embeddings",
+		checkCommand: "mnemex --version",
+		website: "https://github.com/MadAppGang/mnemex",
+		category: "ai-coding",
+		packageManager: "bun",
+		packageName: "mnemex",
+	},
+	{
+		name: "claudish",
+		displayName: "Claudish",
+		description: "Run Claude Code with OpenRouter models (Grok, GPT-5, Gemini)",
+		checkCommand: "claudish --version",
+		website: "https://github.com/MadAppGang/claudish",
+		category: "ai-coding",
+		packageManager: "bun",
+		packageName: "claudish",
+	},
+	{
+		name: "claude",
+		displayName: "Claude Code",
+		description: "Anthropic official agentic coding tool",
+		checkCommand: "claude --version",
+		website: "https://claude.ai/code",
+		category: "ai-coding",
+		packageManager: "npm",
+		packageName: "@anthropic-ai/claude-code",
+	},
+	{
+		name: "codex",
+		displayName: "OpenAI Codex",
+		description:
+			"Lightweight coding agent from OpenAI that runs in your terminal",
+		checkCommand: "codex --version",
+		website: "https://github.com/openai/codex",
+		category: "ai-coding",
+		packageManager: "npm",
+		packageName: "@openai/codex",
+	},
+	{
+		name: "gemini",
+		displayName: "Gemini CLI",
+		description: "Google AI agent with 1M token context, free tier available",
+		checkCommand: "gemini --version",
+		website: "https://github.com/google-gemini/gemini-cli",
+		category: "ai-coding",
+		packageManager: "npm",
+		packageName: "@google/gemini-cli",
+	},
+	{
+		name: "qwen",
+		displayName: "Qwen Code",
+		description: "Alibaba coding agent optimized for Qwen3-Coder models",
+		checkCommand: "qwen --version",
+		website: "https://github.com/QwenLM/qwen-code",
+		category: "ai-coding",
+		packageManager: "npm",
+		packageName: "@qwen-code/qwen-code",
+	},
+	{
+		name: "cline",
+		displayName: "Cline",
+		description:
+			"Autonomous coding agent with plan & act, checkpoints, browser use",
+		checkCommand: "cline --version",
+		website: "https://cline.bot",
+		category: "ai-coding",
+		packageManager: "npm",
+		packageName: "cline",
+	},
+	{
+		name: "opencode",
+		displayName: "OpenCode",
+		description: "Open source AI coding agent trusted by 400k+ developers",
+		checkCommand: "opencode --version",
+		website: "https://opencode.ai",
+		category: "ai-coding",
+		packageManager: "npm",
+		packageName: "opencode-ai",
+	},
+	{
+		name: "aider",
+		displayName: "Aider",
+		description: "AI pair programming - works with Claude, GPT-4, local models",
+		checkCommand: "aider --version",
+		website: "https://aider.chat",
+		category: "ai-coding",
+		packageManager: "pip",
+		packageName: "aider-chat",
+	},
+	{
+		name: "crush",
+		displayName: "Crush",
+		description: "AI coding assistant from Charm with terminal-native UX",
+		checkCommand: "crush --version",
+		website: "https://github.com/charmbracelet/crush",
+		category: "ai-coding",
+		packageManager: "npm",
+		packageName: "@charmland/crush",
+	},
+];