magus-cli 0.0.0-placeholder → 7.0.0

package/src/services/version-check.ts

@@ -0,0 +1,127 @@
+import semver from "semver";
+import pkg from "../../package.json";
+
+// Cache the result for the session
+let cachedResult: VersionCheckResult | null = null;
+
+export interface VersionCheckResult {
+	currentVersion: string;
+	latestVersion: string;
+	updateAvailable: boolean;
+	updateType?: "major" | "minor" | "patch";
+}
+
+/**
+ * Get the current version from package.json.
+ * Static import so it resolves inside a `bun build --compile` binary — a
+ * dynamic require("../../package.json") returns no `.version` there.
+ */
+export function getCurrentVersion(): string {
+	return (pkg as { version?: string }).version ?? "0.0.0";
+}
+
+/**
+ * Fetch the latest version from npm registry
+ * Uses a short timeout to avoid blocking startup
+ */
+async function fetchLatestVersion(): Promise<string | null> {
+	try {
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), 3000); // 3s timeout
+
+		const response = await fetch("https://registry.npmjs.org/magus/latest", {
+			signal: controller.signal,
+			headers: {
+				Accept: "application/json",
+				// Always revalidate — a CDN/HTTP-cached response serves a stale
+				// "latest" right after a release (the 4.25-vs-4.26 flicker).
+				"Cache-Control": "no-cache",
+			},
+		});
+
+		clearTimeout(timeout);
+
+		if (!response.ok) {
+			return null;
+		}
+
+		const data = (await response.json()) as { version?: string };
+		return data.version || null;
+	} catch {
+		// Network error, timeout, or parse error - silently fail
+		return null;
+	}
+}
+
+/**
+ * Determine the type of update (major, minor, patch)
+ */
+function getUpdateType(
+	current: string,
+	latest: string,
+): "major" | "minor" | "patch" | undefined {
+	const currentParsed = semver.parse(current);
+	const latestParsed = semver.parse(latest);
+
+	if (!currentParsed || !latestParsed) return undefined;
+
+	if (latestParsed.major > currentParsed.major) return "major";
+	if (latestParsed.minor > currentParsed.minor) return "minor";
+	if (latestParsed.patch > currentParsed.patch) return "patch";
+
+	return undefined;
+}
+
+/**
+ * Check if a new version is available.
+ * Returns the session-cached result unless `force` requests a fresh check.
+ */
+export async function checkForUpdates(
+	force = false,
+): Promise<VersionCheckResult> {
+	// Return the session-cached result unless a fresh check is forced — a periodic
+	// re-check passes force:true so a release landing mid-session updates the banner.
+	if (!force && cachedResult) {
+		return cachedResult;
+	}
+
+	const currentVersion = getCurrentVersion();
+	const latestVersion = await fetchLatestVersion();
+
+	if (!latestVersion) {
+		// Couldn't fetch, assume no update
+		cachedResult = {
+			currentVersion,
+			latestVersion: currentVersion,
+			updateAvailable: false,
+		};
+		return cachedResult;
+	}
+
+	// Guard: never let a malformed version crash the update check.
+	const updateAvailable =
+		semver.valid(latestVersion) != null &&
+		semver.valid(currentVersion) != null &&
+		semver.gt(latestVersion, currentVersion);
+
+	cachedResult = {
+		currentVersion,
+		latestVersion,
+		updateAvailable,
+		updateType: updateAvailable
+			? getUpdateType(currentVersion, latestVersion)
+			: undefined,
+	};
+
+	return cachedResult;
+}
+
+/**
+ * Format update message for display
+ */
+export function formatUpdateMessage(result: VersionCheckResult): string {
+	if (!result.updateAvailable) return "";
+
+	const typeLabel = result.updateType ? ` (${result.updateType})` : "";
+	return `Update available: v${result.currentVersion} → v${result.latestVersion}${typeLabel}. Run: npm i -g magus-cli`;
+}

package/src/services/version-snapshot.ts

@@ -0,0 +1,189 @@
+/**
+ * version-snapshot.ts — detect plugin changes that happened outside magus.
+ *
+ * Plugins get updated by things magus does not control: Claude Code's own
+ * `plugin install`/`update`, or a direct CLI
+ * call. All of them write `installed_plugins.json`; none of them tell the user
+ * anything the next time magus opens, so versions move underfoot silently.
+ *
+ * Rather than log what magus itself did — which misses every other source —
+ * this records what magus last *saw* installed and diffs against reality on
+ * load. Any change is reported, regardless of who made it.
+ *
+ * The snapshot is advisory UI state, kept separate from the update-check cache
+ * so a TTL expiry or a corrupt cache can never make plugins look changed.
+ */
+
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * Sentinel recorded by Claude Code for a plugin that is installed but whose
+ * version is unknown — every plugin in the official Anthropic marketplace uses
+ * it. It is not a real version and must never be rendered as one.
+ */
+export const UNKNOWN_VERSION = "0.0.0";
+
+/** True when a version string carries no usable information. */
+export function isKnownVersion(v: string | undefined): v is string {
+	return !!v && v !== UNKNOWN_VERSION;
+}
+
+export type PluginChangeKind = "installed" | "updated";
+
+export interface PluginChange {
+	pluginId: string;
+	kind: PluginChangeKind;
+	/** Previous version. Only set for "updated", and always a known version. */
+	from?: string;
+	/** Current version. May be UNKNOWN_VERSION — callers must not render it raw. */
+	to: string;
+}
+
+interface SnapshotFile {
+	/**
+	 * Legacy flat baseline: pluginId -> version, with no record of which project
+	 * it was observed from. Kept only so an existing file can be migrated.
+	 */
+	seen?: Record<string, string>;
+	/**
+	 * projectPath -> (pluginId -> installedVersion) as of the last time magus
+	 * rendered that project.
+	 *
+	 * Versions are per-project (installed_plugins.json keys installs by
+	 * projectPath), but this file is global. A single flat map therefore let two
+	 * projects legitimately on different versions overwrite each other's
+	 * baseline, and every differing plugin was badged "updated" on the next
+	 * render — a change that never happened. Keying by project removes the
+	 * cross-talk entirely.
+	 */
+	byProject?: Record<string, Record<string, string>>;
+	/** Set on the run that first created the baseline. */
+	seededAt: string;
+	updatedAt: string;
+}
+
+/**
+ * Honour CLAUDE_CONFIG_DIR — the same override Claude Code itself uses.
+ *
+ * `os.homedir()` reads the passwd database on macOS and ignores $HOME, so a
+ * test that only overrides HOME writes to the operator's real snapshot file.
+ * That is not hypothetical: it happened while building the tests for this fix.
+ */
+function snapshotPath(): string {
+	const configDir =
+		process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+	return path.join(configDir, "magus-version-snapshot.json");
+}
+
+async function read(): Promise<SnapshotFile | null> {
+	try {
+		const raw = await fs.readFile(snapshotPath(), "utf-8");
+		const data = JSON.parse(raw) as SnapshotFile;
+		if (!data) return null;
+		const hasFlat = typeof data.seen === "object" && data.seen !== null;
+		const hasByProject =
+			typeof data.byProject === "object" && data.byProject !== null;
+		if (!hasFlat && !hasByProject) return null;
+		return data;
+	} catch {
+		return null; // absent or corrupt — treated as "no baseline yet"
+	}
+}
+
+/**
+ * Diff what is installed now against the previous snapshot.
+ *
+ * Three cases are deliberately silent, because each reflects magus's own
+ * knowledge changing rather than anything happening to the user's plugins:
+ *
+ *  1. No baseline (first run). Every plugin would otherwise be reported as
+ *     newly installed on the very first launch — a guaranteed false flood that
+ *     trains the user to ignore the badge. The first run seeds and says nothing.
+ *
+ *  2. A version moving to or from UNKNOWN_VERSION. That is magus learning
+ *     (or losing) a version it could not previously resolve — notably after
+ *     v4.22.0 taught it to read the registry — not the plugin changing.
+ *
+ *  3. A plugin disappearing. Uninstalls are visible elsewhere; nothing to badge.
+ *
+ * A downgrade IS reported: rolling back is a real change worth surfacing.
+ */
+export function diffVersions(
+	previous: Record<string, string> | null,
+	current: Record<string, string>,
+): PluginChange[] {
+	if (!previous) return [];
+
+	const changes: PluginChange[] = [];
+	for (const [pluginId, to] of Object.entries(current)) {
+		const from = previous[pluginId];
+
+		// Never seen before → newly installed, not an update. There is no
+		// meaningful "from", and `to` may legitimately be UNKNOWN_VERSION.
+		if (from === undefined) {
+			changes.push({ pluginId, kind: "installed", to });
+			continue;
+		}
+
+		if (from === to) continue;
+
+		// One side carries no real version: we learned or lost it, nothing moved.
+		if (!isKnownVersion(from) || !isKnownVersion(to)) continue;
+
+		changes.push({ pluginId, kind: "updated", from, to });
+	}
+	return changes;
+}
+
+/**
+ * Load the baseline for one project, or null when that project has none.
+ *
+ * A project seen for the first time returns null, so `diffVersions` stays
+ * silent — the same rule as a first ever run. That is deliberate: opening
+ * magus in a new project must not badge every plugin as "updated" just
+ * because this file has never seen that path before.
+ *
+ * A pre-migration flat file is adopted as the baseline for whichever project
+ * asks first, which is the closest thing to the truth it contains.
+ */
+export async function loadSeenVersions(
+	projectPath: string,
+): Promise<Record<string, string> | null> {
+	const data = await read();
+	if (!data) return null;
+	const scoped = data.byProject?.[projectPath];
+	if (scoped) return scoped;
+	// Legacy flat baseline, project unknown — use it once, then it is replaced
+	// by per-project entries on save.
+	if (data.seen && !data.byProject) return data.seen;
+	return null;
+}
+
+/**
+ * Persist what is installed now, so the same change is not reported twice.
+ * Best-effort: a failure here must never break the UI — it only means the badge
+ * shows again next launch.
+ */
+export async function saveSeenVersions(
+	projectPath: string,
+	current: Record<string, string>,
+): Promise<void> {
+	try {
+		const file = snapshotPath();
+		await fs.mkdir(path.dirname(file), { recursive: true });
+		const existing = await read();
+		const now = new Date().toISOString();
+		const payload: SnapshotFile = {
+			// Other projects' baselines are preserved — writing only this project's
+			// slot is the entire point of the fix.
+			byProject: { ...(existing?.byProject ?? {}), [projectPath]: current },
+			seededAt: existing?.seededAt ?? now,
+			updatedAt: now,
+		};
+		await fs.writeFile(file, JSON.stringify(payload, null, 2), "utf-8");
+	} catch {
+		// ignore
+	}
+}

package/src/tui.tsx

@@ -0,0 +1,112 @@
+/**
+ * The interactive TUI: renderer creation, theme resolution, and the React root.
+ *
+ * Split out of `main.tsx` so that nothing on a non-interactive path — above all
+ * `magus hook …`, which Claude Code runs on every matching tool call — has
+ * to load `@opentui/*` or `src/ui/` to reach its own code. `main.tsx` imports
+ * this module dynamically, at the last possible moment.
+ */
+
+import { RGBA, type ThemeMode, createCliRenderer } from "@opentui/core";
+import { createRoot } from "@opentui/react";
+import { App } from "./ui/App.js";
+import { setThemeMode } from "./ui/theme-mode.js";
+import { type ThemeEnv, resolveTheme } from "./ui/theme-resolve.js";
+
+export interface StartTuiOptions {
+	/** From `--theme`, already validated by the router. */
+	theme?: ThemeMode;
+	/** The theme variables, snapshotted in main.tsx BEFORE any .env merge. */
+	env: ThemeEnv;
+	/** stdin AND stdout are TTYs. Decided by the caller. */
+	isInteractive: boolean;
+}
+
+/**
+ * Start the TUI. Never resolves — the app runs until the user exits.
+ */
+export async function startTui({
+	theme,
+	env,
+	isInteractive,
+}: StartTuiOptions): Promise<void> {
+	// Create OpenTUI renderer (handles alternate screen buffer automatically).
+	//
+	// The background is the terminal's own, not a colour of ours: painting an
+	// absolute fill would box the UI into whatever theme we guessed. OpenTUI's
+	// built-in default for unstyled cells is truecolor white, which is why every
+	// element now names an adaptive colour explicitly — see src/ui/theme.ts.
+	// The mouse is ON, everywhere — it carries real features now: the wheel
+	// scrolls the pane under the cursor, and a drag selects text from ONE pane
+	// at a time (terminal-native selection is a screen-wide rectangle that
+	// grabs both columns), OSC 52-copied on release below.
+	//
+	// This deliberately includes tmux. Two earlier revisions got this wrong in
+	// opposite directions: one disabled the mouse everywhere on the theory that
+	// capture breaks tmux-level pane clicking, the next kept it off only inside
+	// tmux. Both dated from when magus had no mouse features, so disabling
+	// cost nothing. MEASURED on a heavily tmux'd machine: tmux forwards mouse
+	// to a pane application that asks for it (htop in the same session took
+	// clicks and wheel fine while magus sat inert), and tmux's own `mouse`
+	// option keeps governing pane management. Terminal-native selection stays
+	// reachable via Shift+drag in most terminals.
+	//
+	// enableMouseMovement (mode-1003 "report all motion") stays off — selection
+	// needs only button-held drag events, which button reporting delivers.
+	const renderer = await createCliRenderer({
+		backgroundColor: RGBA.defaultBackground(),
+		useMouse: true,
+		enableMouseMovement: false,
+	});
+
+	// Mouse selection → system clipboard, on release. OSC 52 survives SSH;
+	// terminals that block it simply ignore the sequence. Never fires where the
+	// mouse is off, so the tmux path pays nothing.
+	renderer.on("selection", (selection: { getSelectedText(): string }) => {
+		const text = selection?.getSelectedText() ?? "";
+		if (text.length > 0) renderer.copyToClipboardOSC52(text);
+	});
+
+	// Resolve light vs dark once: --theme, MAGUS_THEME, TERM_THEME, the OSC
+	// probe, COLORFGBG, dark — see src/ui/theme-resolve.ts. Only the disabled-row
+	// tint and the chips need this (src/ui/theme-mode.ts explains why that one
+	// case cannot be solved the way the rest of the palette is).
+	//
+	// The renderer sends OSC 10/11 at creation regardless: @opentui/core 0.1.107
+	// has no option to suppress it. So the rule "TERM_THEME skips the probe" is
+	// satisfied by NOT AWAITING — when steps 1-3 answer, `probe` is never called,
+	// `waitForThemeMode(250)` never runs, first paint is not delayed, and
+	// `renderer.themeMode` is never read anywhere in magus. Any late reply the
+	// terminal sends is consumed by OpenTUI's own handleSequence and ignored here.
+	const { mode } = await resolveTheme({
+		flag: theme,
+		env,
+		isInteractive,
+		probe: () => renderer.waitForThemeMode(250).catch(() => null),
+	});
+	setThemeMode(mode);
+
+	const root = createRoot(renderer);
+
+	// Cleanup function to restore terminal
+	const cleanup = () => {
+		root.unmount();
+		renderer.destroy(); // CRITICAL: Never use process.exit() directly
+	};
+
+	// Handle cleanup on exit signals
+	const handleExit = () => {
+		cleanup();
+		// Exit after cleanup completes
+		process.exit(0);
+	};
+
+	process.on("SIGINT", handleExit);
+	process.on("SIGTERM", handleExit);
+
+	// Render the OpenTUI app with exit handler
+	root.render(<App onExit={handleExit} />);
+
+	// Wait indefinitely (app runs until user exits)
+	await new Promise(() => {});
+}

package/src/types/bun.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The sliver of Bun's global this project actually uses.
+ *
+ * `@types/bun` is deliberately NOT a dependency — `utils/command-utils.ts` says
+ * so where it reaches for Node's `fs` instead of `Bun.which` — and the whole
+ * package would be pulled in to type two properties. `cli/hook.ts` reads its
+ * payload from `Bun.stdin.stream()` because that is the fastest path on the
+ * hottest code magus has (a PreToolUse hook runs on every Agent call), so
+ * the global is declared here rather than the call being rewritten.
+ * `services/tool-probe.ts` reads uv's `uv-receipt.toml` with `Bun.TOML.parse`
+ * (the receipt decides whether uv's silence may be read as "current"); a
+ * missing parser degrades to "cannot tell", so the member is optional.
+ *
+ * Keep this MINIMAL. Every member added here is a member nobody checks against
+ * the real runtime; a full mirror of Bun's API would be a second, worse copy of
+ * `@types/bun` that drifts silently. If this grows past a few members, take the
+ * dependency instead.
+ */
+
+declare namespace Bun {
+	const stdin: {
+		stream(): AsyncIterable<Uint8Array>;
+	};
+	const TOML: {
+		parse(text: string): unknown;
+	};
+}

package/src/types/gitignore.ts

@@ -0,0 +1,68 @@
+/**
+ * Types for the gitignore manager: a three-tier (built-in → global → project)
+ * manifest system that declares which paths must be ignored and which must
+ * stay tracked. Last-wins on conflict across tiers; intra-tier conflicts throw.
+ */
+
+export type RuleAction = "ignore" | "track";
+
+export type Tier = "builtin" | "global" | "project" | "profile";
+
+/** A user-authored manifest, deserialized from JSON. */
+export interface GitignoreManifest {
+	/** Paths or globs that must be excluded from git. */
+	ignore: string[];
+	/** Paths that must remain tracked even if a parent is in ignore. */
+	track: string[];
+	/** Optional template names to merge in (e.g. "common-dev"). */
+	extends?: string[];
+}
+
+/** A single rule after tier resolution. */
+export interface ResolvedRule {
+	pattern: string;
+	action: RuleAction;
+	source: Tier;
+}
+
+/** When two tiers disagree on a pattern, the higher-precedence tier wins. */
+export interface ResolvedConflict {
+	pattern: string;
+	winner: Tier;
+	losers: Array<{ tier: Tier; action: RuleAction }>;
+}
+
+export interface ResolvedManifest {
+	rules: ResolvedRule[];
+	conflicts: ResolvedConflict[];
+}
+
+/**
+ * Categorized violation state. The detector inspects the working tree against
+ * the resolved manifest and emits one of these per offending path.
+ *
+ * - tracked-but-should-ignore: path is in git index, manifest says ignore
+ * - ignored-but-should-track:  path matches .gitignore, manifest says track
+ * - untracked-and-should-track: path exists but neither tracked nor ignored;
+ *                                manifest says it should be tracked
+ * - missing-from-gitignore:    path is in manifest.ignore but no .gitignore line
+ *                                covers it (and the path isn't currently tracked)
+ */
+export type ViolationKind =
+	| "tracked-but-should-ignore"
+	| "ignored-but-should-track"
+	| "untracked-and-should-track"
+	| "missing-from-gitignore";
+
+export interface Violation {
+	kind: ViolationKind;
+	path: string;
+	/** Which tier asserted the rule that's being violated. */
+	source: Tier;
+	/**
+	 * "safe"        — fix is purely additive (append a .gitignore line)
+	 * "destructive" — fix mutates git index (`git rm --cached`, `git add`,
+	 *                  removing existing .gitignore lines)
+	 */
+	severity: "safe" | "destructive";
+}