magus-cli 0.0.0-placeholder → 7.1.0

package/src/services/dotenv.ts

@@ -0,0 +1,181 @@
+import { lstatSync, readFileSync, statSync } from "node:fs";
+import type { Stats } from "node:fs";
+import path from "node:path";
+
+/**
+ * Load the project's .env into the process environment — deliberately, in our
+ * own code, with every failure downgraded to a warning.
+ *
+ * Bun's standalone-executable autoload used to do this for free. It is compiled
+ * OFF now (see scripts/build-binaries.ts): Bun 1.4.0 aborts inside that autoload
+ * when .env is a symlink pointing at a FIFO — exactly how 1Password serves
+ * secrets into a git worktree — exiting 1 with nothing on stdout or stderr,
+ * before any JavaScript runs and therefore before any error handler exists.
+ * magus simply vanished in every such directory.
+ *
+ * Two rules this loader keeps that the autoload did not:
+ *
+ *   1. Only regular files are read. A FIFO, socket or device is skipped, never
+ *      opened, because opening a pipe BLOCKS until some process opens the other
+ *      end — with no writer standing by, magus hangs on startup instead of
+ *      running. That is the whole reason. It is NOT that reading would steal
+ *      another process's secrets: 1Password's pipe re-serves its contents on
+ *      every open, and `readFileSync` reads it correctly (`Bun.file().text()`
+ *      is the API that hangs on a FIFO). An earlier version of this comment,
+ *      the warning text, and the 4.42.1 changelog all claimed the one-reader
+ *      story; it is wrong, so do not restore it.
+ *   2. Nothing here is fatal. A missing, unreadable or malformed .env produces a
+ *      warning and magus carries on. Managing ~/.claude must never depend on
+ *      the state of whatever directory you happen to be standing in.
+ *
+ * A real environment variable always beats a file, matching dotenv convention;
+ * a later file beats an earlier one.
+ */
+
+/** Files loaded, in order. A later file overrides an earlier one. */
+const ENV_FILES = [".env", ".env.local"] as const;
+
+export interface DotenvOutcome {
+	/** Files actually parsed, in the order applied. */
+	loaded: string[];
+	/** Names newly set. A pre-existing variable is never overwritten. */
+	applied: string[];
+	/** One line per file skipped or failed. Print these; never throw them. */
+	warnings: string[];
+}
+
+/**
+ * Parse dotenv text. Best-effort by design: an unparseable line is skipped
+ * rather than raised, because a broken .env must not be able to stop magus.
+ * Values spanning several lines are not supported.
+ */
+export function parseDotenv(text: string): Record<string, string> {
+	const out: Record<string, string> = {};
+
+	for (const rawLine of text.split(/\r?\n/)) {
+		const line = rawLine.trim();
+		if (line === "" || line.startsWith("#")) continue;
+
+		const eq = line.indexOf("=");
+		if (eq <= 0) continue;
+
+		let key = line.slice(0, eq).trim();
+		if (key.startsWith("export ")) key = key.slice("export ".length).trim();
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+
+		let value = line.slice(eq + 1).trim();
+		const quote = value[0];
+		const quoted =
+			(quote === '"' || quote === "'") &&
+			value.length > 1 &&
+			value.endsWith(quote);
+
+		if (quoted) {
+			value = value.slice(1, -1);
+			// Escapes are a double-quote feature; single quotes stay literal.
+			if (quote === '"') {
+				value = value
+					.replace(/\\n/g, "\n")
+					.replace(/\\r/g, "\r")
+					.replace(/\\t/g, "\t");
+			}
+		} else {
+			// An unquoted value ends at the first " #" comment.
+			const hash = value.indexOf(" #");
+			if (hash !== -1) value = value.slice(0, hash).trimEnd();
+		}
+
+		out[key] = value;
+	}
+
+	return out;
+}
+
+/** What a non-regular entry actually is, for a warning a human can act on. */
+function describeKind(info: Stats): string {
+	if (info.isFIFO()) {
+		return "it is a named pipe; opening one blocks until a writer appears, and magus must not hang before it starts";
+	}
+	if (info.isSocket()) return "it is a socket, not a regular file";
+	if (info.isDirectory()) return "it is a directory, not a regular file";
+	if (info.isBlockDevice() || info.isCharacterDevice()) {
+		return "it is a device, not a regular file";
+	}
+	return "it is not a regular file";
+}
+
+function reason(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Read .env and .env.local from `cwd` into `env`. Never throws.
+ *
+ * Returns what was loaded and, in `warnings`, every reason a file was skipped or
+ * failed — the caller decides how to surface them.
+ */
+export function loadProjectDotenv(
+	cwd: string = process.cwd(),
+	env: Record<string, string | undefined> = process.env,
+): DotenvOutcome {
+	const outcome: DotenvOutcome = { loaded: [], applied: [], warnings: [] };
+
+	// Merge every file BEFORE touching `env`. Applying file by file would make
+	// the "never overwrite" rule below fire against .env's own values, so .env
+	// would silently beat .env.local — the opposite of the intended precedence.
+	const merged: Record<string, string> = {};
+
+	for (const name of ENV_FILES) {
+		const file = path.join(cwd, name);
+
+		// lstat first, so a symlink is recognised as one: the warning should name
+		// the file the user sees, while the decision is made about its target.
+		let info: Stats;
+		try {
+			info = lstatSync(file);
+		} catch {
+			continue; // Absent. That is the ordinary case, not a problem.
+		}
+
+		if (info.isSymbolicLink()) {
+			try {
+				info = statSync(file);
+			} catch {
+				outcome.warnings.push(`skipped ${name} — the symlink does not resolve`);
+				continue;
+			}
+		}
+
+		if (!info.isFile()) {
+			outcome.warnings.push(`skipped ${name} — ${describeKind(info)}`);
+			continue;
+		}
+
+		let text: string;
+		try {
+			text = readFileSync(file, "utf8");
+		} catch (error) {
+			outcome.warnings.push(`could not read ${name} — ${reason(error)}`);
+			continue;
+		}
+
+		let parsed: Record<string, string>;
+		try {
+			parsed = parseDotenv(text);
+		} catch (error) {
+			outcome.warnings.push(`could not parse ${name} — ${reason(error)}`);
+			continue;
+		}
+
+		outcome.loaded.push(name);
+		Object.assign(merged, parsed); // A later file beats an earlier one.
+	}
+
+	for (const [key, value] of Object.entries(merged)) {
+		if (env[key] !== undefined) continue; // A real variable always wins.
+		env[key] = value;
+		outcome.applied.push(key);
+	}
+
+	return outcome;
+}

package/src/services/git-worktree.ts

@@ -0,0 +1,129 @@
+/**
+ * git-worktree.ts — which other directories count as "the same project" as this one.
+ *
+ * `installed_plugins.json` keys one entry per `projectPath`, so a directory that
+ * nobody has run `claude plugin install` in has no rows at all. A freshly created
+ * git worktree is exactly that: measured on a real machine, 750 project-scope rows
+ * across 76 plugin keys and not one of them for the new worktree.
+ *
+ * Claude Code does not care. Its loader is not gated on the current project — a
+ * worktree with zero rows resolves `installPath` from another project's row and
+ * loads from cache (measured, `ai-docs/plugin-system-state-model.md`). magus
+ * mirrored the registry faithfully instead, so it reported every plugin as missing
+ * and offered to install things that were already working.
+ *
+ * The fix is to ask a narrower question than "does the loader find something
+ * somewhere": inherit rows only from directories that are the *same repository*.
+ * That covers both ways a project path can miss its own rows —
+ *
+ *   1. a linked worktree, whose main working tree holds the rows
+ *   2. a subdirectory of a checkout, where the rows sit at the repo root
+ *
+ * — under one rule, and never inherits from an unrelated project, which would be
+ * claiming a version we cannot attribute.
+ */
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+
+function git(
+	cwd: string,
+	args: string[],
+): Promise<{ code: number; out: string }> {
+	return new Promise((resolve) => {
+		const child = spawn("git", args, {
+			cwd,
+			stdio: ["ignore", "pipe", "ignore"],
+		});
+		let out = "";
+		child.stdout.on("data", (d) => {
+			out += String(d);
+		});
+		// Never let a wedged git block the UI.
+		const timer = setTimeout(() => {
+			child.kill();
+			resolve({ code: -1, out: "" });
+		}, 5000);
+		timer.unref?.();
+		const settle = (code: number, text: string) => {
+			clearTimeout(timer);
+			resolve({ code, out: text });
+		};
+		child.on("error", () => settle(-1, ""));
+		child.on("close", (code) => settle(code ?? -1, out.trim()));
+	});
+}
+
+/**
+ * Session cache. Keyed by resolved project path — the repository layout cannot
+ * change under a running magus in any way worth tracking, and the resolution
+ * runs once per plugin per scope otherwise (24+ plugins × 3 scopes of `git`).
+ */
+const cache = new Map<string, string[]>();
+
+export function clearWorktreeCache(): void {
+	cache.clear();
+}
+
+/**
+ * Directories whose registry rows this project may inherit, nearest first.
+ *
+ * Returns `[]` — never a guess — when the question cannot be answered honestly:
+ * git missing, not a repository, a bare repo with no working tree, or the path
+ * already being the repository root. Inheriting nothing restores the previous
+ * behaviour for that path, which is the safe direction: a false negative shows
+ * an "install" the user does not need, a false positive hides a real one.
+ */
+export async function inheritablePaths(projectPath: string): Promise<string[]> {
+	const key = path.resolve(projectPath);
+	const cached = cache.get(key);
+	if (cached) return cached;
+	const { paths, answered } = await resolveInheritable(key);
+	// Only cache an answer git actually gave. A timeout or a transient spawn
+	// failure would otherwise pin an empty result for the rest of the session,
+	// turning one slow moment into a persistent wrong "not installed".
+	if (answered) cache.set(key, paths);
+	return paths;
+}
+
+async function resolveInheritable(
+	dir: string,
+): Promise<{ paths: string[]; answered: boolean }> {
+	const candidates: string[] = [];
+
+	// Independent queries, so run them together: sequentially, two wedged git calls
+	// would stall the first paint for the full 10s rather than 5.
+	const [top, list] = await Promise.all([
+		// The root of whichever working tree we are standing in. Covers a subdirectory
+		// of a checkout, and is the nearer answer when both apply.
+		git(dir, ["rev-parse", "--show-toplevel"]),
+		// The main working tree, which `git worktree list` always lists first. This is
+		// the row-bearing directory for a linked worktree.
+		git(dir, ["worktree", "list", "--porcelain"]),
+	]);
+
+	if (top.code === 0 && top.out) candidates.push(path.resolve(top.out));
+
+	if (list.code === 0 && list.out) {
+		const firstRecord = list.out.split("\n\n")[0].split("\n");
+		// A bare repo is listed with a `bare` line and has no working tree to inherit.
+		const isBare = firstRecord.some((l) => l.trim() === "bare");
+		const line = firstRecord.find((l) => l.startsWith("worktree "));
+		if (!isBare && line) {
+			candidates.push(path.resolve(line.slice("worktree ".length).trim()));
+		}
+	}
+
+	// "Not a repository" is a real answer worth caching; "git never replied" is not.
+	const answered = top.code !== -1 || list.code !== -1;
+
+	// Drop this project itself and any duplicate, preserving nearest-first order.
+	const seen = new Set<string>([dir]);
+	const inheritable: string[] = [];
+	for (const candidate of candidates) {
+		if (seen.has(candidate)) continue;
+		seen.add(candidate);
+		inheritable.push(candidate);
+	}
+	return { paths: inheritable, answered };
+}

package/src/services/github-budget.ts

@@ -0,0 +1,274 @@
+/**
+ * github-budget.ts — one place that knows when we are allowed to call GitHub.
+ *
+ * magus talks to two GitHub hosts from several services, and they enforce
+ * separate budgets:
+ *
+ *   api.github.com            60 req/hr unauthenticated, and it TELLS you:
+ *                             x-ratelimit-remaining / x-ratelimit-reset / retry-after
+ *   raw.githubusercontent.com rate-limited too, and it tells you NOTHING —
+ *                             measured 2026-08-17: a 429 carried no retry-after
+ *                             and no x-ratelimit-* header, only a request id.
+ *
+ * That asymmetry is the whole design problem. For one host we can state exactly
+ * when the window reopens; for the other any specific time would be invented. So
+ * a cooldown records WHERE its timing came from, and the UI says "resets in 4m"
+ * only when GitHub actually said so, and "next attempt in 30s" — our own
+ * schedule, honestly labelled — when it did not.
+ *
+ * Two jobs:
+ *  1. Stop sending requests that are already known to fail. Every service shares
+ *     one bucket per host, so the skills screen's raw fetches and the plugin
+ *     catalog fetches must share one gate — otherwise each rediscovers the limit
+ *     by burning more attempts against it.
+ *  2. Report when the next attempt is due, so the UI can show a countdown and
+ *     retry itself instead of asking the user to guess.
+ */
+
+import {
+	clearStoredCooldown,
+	readStoredCooldowns,
+	writeStoredCooldown,
+} from "./catalog-cache-store.js";
+
+/** Hosts we gate. Anything else is not budgeted. */
+export type GitHubHost = "api.github.com" | "raw.githubusercontent.com";
+
+export interface Cooldown {
+	host: GitHubHost;
+	/** Wall-clock ms when the next attempt is allowed. */
+	until: number;
+	/**
+	 * True when `until` came from GitHub's own `retry-after` /
+	 * `x-ratelimit-reset`. False when we derived it from backoff because the
+	 * response carried no timing — the distinction the UI must not blur.
+	 */
+	exact: boolean;
+	/** Consecutive rate-limited responses, driving the backoff. */
+	strikes: number;
+}
+
+const cooldowns = new Map<GitHubHost, Cooldown>();
+
+/**
+ * Load cooldowns recorded by a previous launch.
+ *
+ * Without this the gate is per-process, which for a TUI means per-launch, which
+ * means useless: two consecutive processes each spent six requests rediscovering
+ * the same rate limit. Memoised, so callers may await it unconditionally.
+ */
+let hydrated: Promise<void> | null = null;
+
+export function hydrateGitHubBudget(): Promise<void> {
+	hydrated ??= (async () => {
+		try {
+			const stored = await readStoredCooldowns();
+			for (const [host, cooldown] of Object.entries(stored)) {
+				if (host !== "api.github.com" && host !== "raw.githubusercontent.com") {
+					continue;
+				}
+				// A cooldown already known in this process wins: it is newer.
+				if (cooldowns.has(host)) continue;
+				cooldowns.set(host, { host, ...cooldown });
+			}
+		} catch {
+			// A cache that cannot be read must not stop us making requests.
+		}
+	})();
+	return hydrated;
+}
+
+/**
+ * Backoff for hosts that give no retry timing. Deliberately coarse: a rate limit
+ * measured in minutes is not escaped by retrying in one second, and each wasted
+ * attempt can extend the penalty.
+ */
+const BACKOFF_MS = [30_000, 60_000, 120_000, 300_000, 600_000];
+
+/** Cap on a server-provided window we will honour, so a bad header cannot wedge the UI. */
+const MAX_EXACT_WAIT_MS = 60 * 60_000;
+
+export function hostOf(url: string): GitHubHost | null {
+	try {
+		const { hostname } = new URL(url);
+		if (hostname === "api.github.com") return "api.github.com";
+		if (hostname === "raw.githubusercontent.com")
+			return "raw.githubusercontent.com";
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Parse GitHub's retry timing, if the response carries any.
+ *
+ * `retry-after` is delta-seconds or an HTTP date (RFC 9110). `x-ratelimit-reset`
+ * is epoch SECONDS, not ms — treating it as ms yields a date in 1970 and a
+ * cooldown that expires instantly, which reads as "not rate limited".
+ */
+function parseRetryTiming(headers: Headers, now: number): number | null {
+	const retryAfter = headers.get("retry-after");
+	if (retryAfter) {
+		const seconds = Number(retryAfter);
+		if (Number.isFinite(seconds) && seconds >= 0) {
+			return now + seconds * 1000;
+		}
+		const asDate = Date.parse(retryAfter);
+		if (Number.isFinite(asDate)) return asDate;
+	}
+
+	const reset = headers.get("x-ratelimit-reset");
+	if (reset) {
+		const epochSeconds = Number(reset);
+		if (Number.isFinite(epochSeconds) && epochSeconds > 0) {
+			return epochSeconds * 1000;
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Record a rate-limited response and return the resulting cooldown.
+ *
+ * Call this for 429 and for 403, which is how GitHub reports an exhausted
+ * unauthenticated budget on the REST API.
+ */
+export function recordRateLimit(
+	host: GitHubHost,
+	headers?: Headers,
+	now: number = Date.now(),
+): Cooldown {
+	const strikes = (cooldowns.get(host)?.strikes ?? 0) + 1;
+
+	const fromHeader = headers ? parseRetryTiming(headers, now) : null;
+	if (fromHeader !== null && fromHeader > now) {
+		const cooldown: Cooldown = {
+			host,
+			until: Math.min(fromHeader, now + MAX_EXACT_WAIT_MS),
+			exact: true,
+			strikes,
+		};
+		cooldowns.set(host, cooldown);
+		persist(cooldown);
+		return cooldown;
+	}
+
+	const step = BACKOFF_MS[Math.min(strikes - 1, BACKOFF_MS.length - 1)];
+	const cooldown: Cooldown = {
+		host,
+		// No jitter: this is a single-user desktop tool, not a fleet stampeding
+		// one endpoint. A predictable countdown is worth more here than spread.
+		until: now + (step ?? 30_000),
+		exact: false,
+		strikes,
+	};
+	cooldowns.set(host, cooldown);
+	persist(cooldown);
+	return cooldown;
+}
+
+/**
+ * Write-behind, so `recordRateLimit` stays synchronous for its many call sites.
+ *
+ * Fire-and-forget is acceptable here and only here: losing one cooldown write
+ * degrades to the old behaviour (one wasted request next launch), whereas making
+ * every caller async to guarantee it would spread `await` through the fetch path
+ * for no proportional gain.
+ */
+function persist(cooldown: Cooldown): void {
+	void writeStoredCooldown(cooldown.host, {
+		until: cooldown.until,
+		exact: cooldown.exact,
+		strikes: cooldown.strikes,
+	});
+}
+
+/**
+ * A successful response clears the host's cooldown and its accumulated strikes.
+ *
+ * Resetting strikes matters: without it, one bad afternoon leaves the backoff
+ * pinned at ten minutes for the rest of the session even though requests are
+ * succeeding again.
+ */
+export function recordSuccess(host: GitHubHost): void {
+	cooldowns.delete(host);
+	void clearStoredCooldown(host);
+}
+
+/**
+ * Also worth recording: the budget is nearly spent. Lets a caller stop before it
+ * trips the limit rather than after. Only api.github.com reports this.
+ */
+export function remainingFromHeaders(headers: Headers): number | null {
+	const remaining = headers.get("x-ratelimit-remaining");
+	if (!remaining) return null;
+	const n = Number(remaining);
+	return Number.isFinite(n) ? n : null;
+}
+
+/** The active cooldown for a host, or null when calls are allowed. */
+export function cooldownFor(
+	host: GitHubHost,
+	now: number = Date.now(),
+): Cooldown | null {
+	const cooldown = cooldowns.get(host);
+	if (!cooldown) return null;
+	if (cooldown.until <= now) {
+		// Expired. Keep the strike count — it is what makes repeated failures back
+		// off further — but stop blocking.
+		cooldowns.set(host, { ...cooldown, until: now });
+		return null;
+	}
+	return cooldown;
+}
+
+/** Milliseconds until the next attempt is allowed. 0 when allowed now. */
+export function waitMs(host: GitHubHost, now: number = Date.now()): number {
+	const cooldown = cooldownFor(host, now);
+	return cooldown ? cooldown.until - now : 0;
+}
+
+/** Every host currently in cooldown, soonest first. */
+export function activeCooldowns(now: number = Date.now()): Cooldown[] {
+	const active: Cooldown[] = [];
+	for (const host of cooldowns.keys()) {
+		const cooldown = cooldownFor(host, now);
+		if (cooldown) active.push(cooldown);
+	}
+	return active.sort((a, b) => a.until - b.until);
+}
+
+/** Human countdown: "45s", "4m", "1h 12m". */
+export function formatWait(ms: number): string {
+	const totalSeconds = Math.max(0, Math.ceil(ms / 1000));
+	if (totalSeconds < 60) return `${totalSeconds}s`;
+	const minutes = Math.ceil(totalSeconds / 60);
+	if (minutes < 60) return `${minutes}m`;
+	const hours = Math.floor(minutes / 60);
+	return `${hours}h ${minutes % 60}m`;
+}
+
+/**
+ * How to describe a cooldown to the user.
+ *
+ * The two phrasings are not interchangeable. "resets in 4m" is a claim about
+ * GitHub's state and is only sayable when GitHub sent the timing;
+ * "next attempt in 30s" is a claim about our own schedule and is always sayable.
+ */
+export function describeCooldown(
+	cooldown: Cooldown,
+	now: number = Date.now(),
+): string {
+	const wait = formatWait(cooldown.until - now);
+	return cooldown.exact
+		? `GitHub rate limit resets in ${wait}`
+		: `GitHub rate limit — next attempt in ${wait}`;
+}
+
+/** Test seam only. Clears in-memory state and the hydration memo, not the file. */
+export function resetGitHubBudget(): void {
+	cooldowns.clear();
+	hydrated = null;
+}

package/src/services/gitignore-check.ts

@@ -0,0 +1,63 @@
+/**
+ * Read-only gitignore check for the gitignore manager.
+ *
+ * Called from the TUI on startup and from `doctor`. Resolves the manifest, runs
+ * detection, and returns a concise warning when violations exist. Does NOT
+ * auto-apply fixes — the user must open the Git State tab and confirm. This
+ * mirrors the plugin-version-mismatch flow, where the check only *reports* and
+ * the TUI provides the interactive fix dialog.
+ */
+
+import type { Violation } from "../types/gitignore.js";
+import { detectViolations } from "./gitignore-detector.js";
+import { formatViolationSummary } from "./gitignore-fixer.js";
+import { resolveGitignore } from "./gitignore-resolver.js";
+
+export interface GitignoreCheckResult {
+	violationCount: number;
+	warnings: string[];
+}
+
+export async function checkGitignore(
+	cwd: string,
+): Promise<GitignoreCheckResult> {
+	const warnings: string[] = [];
+	try {
+		const resolved = await resolveGitignore(cwd, {
+			logger: (m) => warnings.push(m),
+		});
+		const violations = await detectViolations(cwd, resolved);
+		return {
+			violationCount: violations.length,
+			warnings,
+		};
+	} catch (err) {
+		warnings.push(
+			`[gitignore] check failed: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		return { violationCount: 0, warnings };
+	}
+}
+
+/**
+ * One-line summary suitable for stderr. Returns null when there's
+ * nothing to warn about.
+ */
+export function formatGitignoreWarning(
+	result: GitignoreCheckResult,
+): string | null {
+	if (result.violationCount === 0) return null;
+	return `⚠ ${result.violationCount} git state issue(s) detected. Run: magus → Git State tab to review and fix`;
+}
+
+/**
+ * Verbose multi-line summary, used by the Git State tab when the user wants
+ * to know what's wrong before deciding what to do.
+ */
+export async function describeViolations(
+	cwd: string,
+	violations: Violation[],
+): Promise<string> {
+	void cwd;
+	return formatViolationSummary(violations);
+}