magus-cli 7.9.0 → 7.10.0

package/src/services/deps-plan.ts

@@ -16,30 +16,32 @@
  * Re-running is the recovery: a plan is always built from a fresh probe, so a
  * step whose effect is already present is not planned again; every step is
  * idempotent or writes its result last (a release renames into place); the apt
- * batch starts with `dpkg --configure -a` and waits on the dpkg lock; and only
- * one apply runs at a time per user (`DepsLockBusy`).
+ * batch starts with `dpkg --configure -a` and waits on the dpkg lock; only one
+ * apply runs at a time per user (`DepsLockBusy`); and the temp dirs a killed
+ * apply left in a user prefix are swept by the next one.
  */
 
 import { createHash } from "node:crypto";
 import {
 	chmodSync,
-	closeSync,
+	linkSync,
 	lstatSync,
 	mkdirSync,
 	mkdtempSync,
-	openSync,
 	readFileSync,
+	readdirSync,
 	renameSync,
 	rmSync,
 	unlinkSync,
 	writeFileSync,
-	writeSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
 import {
 	type Arch,
 	BUN_PREFIX,
+	type Bootstrap,
+	type BootstrapTool,
 	type InstallStep,
 	LOCAL_PREFIX,
 	type Os,
@@ -56,6 +58,7 @@ import {
 	pathRcLine,
 	probe,
 	rcFile,
+	rcFileAdding,
 	renderInstall,
 	uvScriptArgv,
 	whyUnselectable,
@@ -96,6 +99,7 @@ export interface PlannedStep {
 	installs: InstallTarget[];
 }
 
+/** A PATH line the user has to add: never one an rc file already has. */
 export interface PathAdvice {
 	prefix: UserPrefix;
 	rcFile: string;
@@ -183,16 +187,49 @@ export function prefixOnPath(prefix: UserPrefix, env: PlanEnv): boolean {
 	return env.path.split(delimiter).some((d) => d === dir || d === `${dir}/`);
 }
 
-/** The PATH line for a prefix, in the user's rc file. */
-export function pathAdviceFor(prefix: UserPrefix, env: PlanEnv): PathAdvice {
-	const info = USER_PREFIXES.find((u) => u.dir === prefix);
+/**
+ * The PATH line for a prefix, in the user's rc file; null when a startup file
+ * of the user's shell already puts the prefix on PATH. Then there is no line
+ * to add: Claude Code started without reading that file, and a restart is the
+ * fix, which an off-path step's remedy and the hook banner say.
+ */
+export function pathAdviceFor(
+	prefix: UserPrefix,
+	env: PlanEnv,
+): PathAdvice | null {
+	if (rcFileAdding(prefix, env.userShell, env.home)) return null;
 	return {
 		prefix,
 		rcFile: rcFile(env.userShell),
-		rcLine: info ? info.rcLine(env.userShell) : "",
+		rcLine: pathRcLine(prefix, env.userShell),
 	};
 }
 
+/**
+ * What to do about `dir` (a user prefix, or another `~/…` or absolute
+ * directory) off the PATH Claude Code starts with: add the line, or — when a
+ * startup file of the user's shell already puts it on PATH — only restart.
+ */
+function pathRemedy(dir: string, env: PlanEnv): string {
+	const adding = rcFileAdding(dir, env.userShell, env.home);
+	return adding
+		? `${adding} already puts ${dir} on PATH: restart Claude Code from a new terminal`
+		: `add  ${pathRcLine(dir, env.userShell)}  to ${rcFile(env.userShell)}, then restart Claude Code from a new terminal`;
+}
+
+/**
+ * The prefix a planned step's installer adds to the user's rc file itself
+ * ({@link Bootstrap.editsRc}), or null. A bootstrap step is named after its
+ * tool: a requirement may bootstrap only the tool it is named after.
+ */
+function rcEditedBy(step: InstallStep): UserPrefix | null {
+	if (step.kind !== "bootstrap" || !(step.name in TOOLCHAIN_BOOTSTRAP)) {
+		return null;
+	}
+	const b: Bootstrap = TOOLCHAIN_BOOTSTRAP[step.name as BootstrapTool];
+	return b.editsRc ? b.prefix : null;
+}
+
 /** A root uv-module step may only come from a plugin of the magus marketplace. */
 function fromMagusMarketplace(bin: ResolvedBin): boolean {
 	return bin.sources.some(
@@ -214,14 +251,13 @@ export function planDeps(
 	env: PlanEnv,
 ): DepsPlan {
 	const unfixable: DepsPlan["unfixable"] = [];
-	const advice = new Map<UserPrefix, PathAdvice>();
+	/** The prefixes off the PATH, in the order they came up. */
+	const offPathPrefixes = new Set<UserPrefix>();
 	const missing: ResolvedBin[] = [];
 	bins.forEach((bin, i) => {
 		const p = presence[i];
 		if (p?.status === "missing") missing.push(bin);
-		if (p?.status === "off-path") {
-			advice.set(p.prefix, pathAdviceFor(p.prefix, env));
-		}
+		if (p?.status === "off-path") offPathPrefixes.add(p.prefix);
 	});
 
 	// A pin the owning plugin's option cannot carry: unfixable whatever the
@@ -325,11 +361,16 @@ export function planDeps(
 		}
 		steps.push(p);
 		const prefix = prefixOf(p.step);
-		if (prefix && !prefixOnPath(prefix, env)) {
-			advice.set(prefix, pathAdviceFor(prefix, env));
-		}
+		if (prefix && !prefixOnPath(prefix, env)) offPathPrefixes.add(prefix);
 	}
-	return { steps, unfixable, pathAdvice: [...advice.values()] };
+	// A prefix whose installer writes the rc line itself gets no line ahead of
+	// it: following one and then running the installer leaves the line twice.
+	const rcEdited = new Set(steps.map((p) => rcEditedBy(p.step)));
+	const pathAdvice = [...offPathPrefixes]
+		.filter((prefix) => !rcEdited.has(prefix))
+		.map((prefix) => pathAdviceFor(prefix, env))
+		.filter((a): a is PathAdvice => a !== null);
+	return { steps, unfixable, pathAdvice };
 }
 
 /**
@@ -397,23 +438,48 @@ export interface ApplyIO {
 }
 
 const DOWNLOAD_TIMEOUT_MS = 10 * 60_000;
+/** Redirects a download follows before it gives up. */
+const MAX_REDIRECTS = 10;
 /** The per-check cap a post-install re-probe runs under: doctor's. */
 const VERIFY_CAP_MS = 60_000;
 
+/**
+ * The body at `url`, every hop of it over https. Redirects are followed here,
+ * one at a time, so a hop that is not https is refused before it is requested:
+ * a bootstrap script has no digest to catch what a plain-http hop could swap.
+ */
+async function httpsDownload(url: string): Promise<Uint8Array> {
+	const signal = AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS);
+	let at = new URL(url);
+	for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+		if (at.protocol !== "https:") {
+			throw new Error(
+				hop === 0
+					? `${url} is not https — refused`
+					: `${url} redirected off https, to ${at.href} — refused`,
+			);
+		}
+		const res = await fetch(at, { redirect: "manual", signal });
+		const location = res.headers.get("location");
+		if (res.status >= 300 && res.status < 400 && location) {
+			await res.body?.cancel();
+			at = new URL(location, at);
+			continue;
+		}
+		if (!res.ok) throw new Error(`HTTP ${res.status} for ${at.href}`);
+		// A fetch that followed a redirect itself reports where it ended up.
+		if (res.url && new URL(res.url).protocol !== "https:") {
+			throw new Error(`${url} redirected off https, to ${res.url} — refused`);
+		}
+		return new Uint8Array(await res.arrayBuffer());
+	}
+	throw new Error(`${url} redirected more than ${MAX_REDIRECTS} times`);
+}
+
 export const REAL_APPLY_IO: ApplyIO = {
 	run: (argv, opts) =>
 		runArgv({ cmd: argv[0] ?? "", args: argv.slice(1) }, opts),
-	download: async (url) => {
-		const res = await fetch(url, {
-			signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
-		});
-		if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
-		// Every URL here is https; a redirect off it is refused, not read.
-		if (new URL(res.url).protocol !== "https:") {
-			throw new Error(`${url} redirected off https, to ${res.url}`);
-		}
-		return new Uint8Array(await res.arrayBuffer());
-	},
+	download: httpsDownload,
 	uid: () => (typeof process.getuid === "function" ? process.getuid() : null),
 	alive: (pid) => {
 		try {
@@ -452,11 +518,11 @@ export interface ApplyOptions {
 	io?: Partial<ApplyIO>;
 }
 
-/** Another apply holds the lock. */
+/** Another apply holds the lock; `pid` is null when its holder is not yet known. */
 export class DepsLockBusy extends Error {
-	constructor(readonly pid: number) {
+	constructor(readonly pid: number | null) {
 		super(
-			`another magus dependency install (pid ${pid}) is running — wait for it, then re-run`,
+			`another magus dependency install${pid === null ? "" : ` (pid ${pid})`} is running — wait for it, then re-run`,
 		);
 		this.name = "DepsLockBusy";
 	}
@@ -467,33 +533,140 @@ export function defaultLockPath(home: string, xdgCacheHome?: string): string {
 	return join(xdgCacheHome || join(home, ".cache"), "magus", "doctor-fix.lock");
 }
 
-/** Take the lock (O_EXCL, holding our pid), taking over one whose pid is gone. */
-function acquireLock(path: string, io: ApplyIO): () => void {
+/** How many times a busy lock is tried, and how long apart. */
+const LOCK_ATTEMPTS = 20;
+const LOCK_RETRY_MS = 50;
+/**
+ * A lock with no pid in it this old was left by a writer that died between
+ * creating it and writing the pid; no live writer is that slow.
+ */
+const EMPTY_LOCK_STALE_MS = 10_000;
+
+const sleep = (ms: number) =>
+	new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/** What the lock file says about its holder. */
+type LockHolder =
+	/** Released between the failed take and this read. */
+	| { kind: "gone" }
+	| { kind: "pid"; pid: number }
+	/** Created by a writer that has not written its pid yet, or never will. */
+	| { kind: "no-pid"; ageMs: number }
+	/** Not a regular file (a dangling symlink, say): no holder ever wrote it. */
+	| { kind: "not-a-lock" };
+
+function readLockHolder(path: string): LockHolder {
+	const gone = (error: unknown): LockHolder => {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return { kind: "gone" };
+		}
+		throw error;
+	};
+	let mtimeMs: number;
+	try {
+		const stat = lstatSync(path);
+		if (!stat.isFile()) return { kind: "not-a-lock" };
+		mtimeMs = stat.mtimeMs;
+	} catch (error) {
+		return gone(error);
+	}
+	let text: string;
+	try {
+		text = readFileSync(path, "utf8").trim();
+	} catch (error) {
+		return gone(error);
+	}
+	const pid = Number.parseInt(text, 10);
+	return Number.isInteger(pid) && pid > 0
+		? { kind: "pid", pid }
+		: { kind: "no-pid", ageMs: Date.now() - mtimeMs };
+}
+
+/** Remove a stale lock; one another taker removed first is just as gone. */
+function removeStaleLock(path: string): void {
+	try {
+		unlinkSync(path);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+}
+
+/**
+ * Take the lock. The pid is written to a file of our own first and the lock is
+ * a hard link to it, so the lock never exists without a pid in it. A live
+ * holder refuses with {@link DepsLockBusy}; one whose pid is gone is taken
+ * over. A lock that vanishes before it is read is free, and taken. A lock with
+ * no pid (another writer between creating and writing it) is busy: it is read
+ * again shortly, and taken over only once it is too old to be mid-write.
+ */
+async function acquireLock(path: string, io: ApplyIO): Promise<() => void> {
 	mkdirSync(dirname(path), { recursive: true });
-	for (let attempt = 0; attempt < 2; attempt++) {
-		try {
-			const fd = openSync(path, "wx", 0o600);
-			writeSync(fd, String(process.pid));
-			closeSync(fd);
-			return () => {
-				try {
-					if (readFileSync(path, "utf8").trim() === String(process.pid)) {
-						unlinkSync(path);
+	const mine = String(process.pid);
+	const staged = `${path}.${mine}`;
+	writeFileSync(staged, mine, { mode: 0o600 });
+	try {
+		for (let attempt = 0; attempt < LOCK_ATTEMPTS; attempt++) {
+			try {
+				linkSync(staged, path);
+				return () => {
+					try {
+						if (readFileSync(path, "utf8").trim() === mine) unlinkSync(path);
+					} catch {
+						// Already gone.
 					}
-				} catch {
-					// Already gone.
-				}
-			};
-		} catch (error) {
-			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-			const pid = Number.parseInt(readFileSync(path, "utf8").trim(), 10);
-			if (Number.isInteger(pid) && pid > 0 && io.alive(pid)) {
-				throw new DepsLockBusy(pid);
+				};
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+			}
+			const holder = readLockHolder(path);
+			if (holder.kind === "gone") continue;
+			if (holder.kind === "not-a-lock") {
+				removeStaleLock(path);
+				continue;
+			}
+			if (holder.kind === "pid") {
+				if (io.alive(holder.pid)) throw new DepsLockBusy(holder.pid);
+				removeStaleLock(path); // its holder is gone
+				continue;
+			}
+			if (holder.ageMs > EMPTY_LOCK_STALE_MS) {
+				removeStaleLock(path);
+				continue;
+			}
+			await sleep(LOCK_RETRY_MS);
+		}
+		throw new DepsLockBusy(null);
+	} finally {
+		rmSync(staged, { force: true });
+	}
+}
+
+/** The temp dir a release step extracts into, inside its destination. */
+const RELEASE_TMP_PREFIX = ".magus-tmp-";
+
+/**
+ * Remove the temp dirs a release step left in a user prefix when its apply was
+ * killed before the step's `finally` ran. Runs holding the lock, so no apply
+ * owns any of them.
+ */
+function sweepStaleTemp(home: string): void {
+	for (const prefix of USER_PREFIXES) {
+		const dir = expandHome(prefix.dir, home);
+		let entries: string[];
+		try {
+			entries = readdirSync(dir);
+		} catch {
+			continue; // no such prefix yet: nothing left behind
+		}
+		for (const entry of entries) {
+			if (!entry.startsWith(RELEASE_TMP_PREFIX)) continue;
+			try {
+				rmSync(join(dir, entry), { recursive: true, force: true });
+			} catch {
+				// One that cannot be removed leaves the rest to sweep.
 			}
-			unlinkSync(path); // stale: its holder is gone
 		}
 	}
-	throw new Error(`could not take ${path}`);
 }
 
 const STEP_TIMEOUT_MS = 15 * 60_000;
@@ -544,8 +717,9 @@ export async function applyDepsPlan(
 	if (plan.steps.length === 0) return [];
 	if (!opts.yes && !(await opts.confirm(plan))) return [];
 	const io: ApplyIO = { ...REAL_APPLY_IO, ...opts.io };
-	const release = acquireLock(opts.lockPath, io);
+	const release = await acquireLock(opts.lockPath, io);
 	try {
+		sweepStaleTemp(opts.env.home);
 		return await applySteps(plan, opts, io);
 	} finally {
 		release();
@@ -618,11 +792,12 @@ async function applySteps(
 		}
 		opts.onEvent?.({ type: "step-start", name: step.name, describe });
 		const started = Date.now();
-		const run = (argv: string[], escalated = false) =>
+		const run = (argv: string[], how: RunHow = {}) =>
 			io.run(argv, {
 				timeoutMs: STEP_TIMEOUT_MS,
-				env: childEnv,
-				...(escalated ? { killGraceMs: SUDO_KILL_GRACE_MS } : {}),
+				env: how.env ? { ...childEnv, ...how.env } : childEnv,
+				...(how.escalated ? { killGraceMs: SUDO_KILL_GRACE_MS } : {}),
+				...(how.captureStdout ? { captureStdout: true } : {}),
 				onOutput: (chunk) =>
 					opts.onEvent?.({ type: "output", name: step.name, chunk }),
 			});
@@ -708,9 +883,10 @@ async function landingDir(
 		step.argv[0] === "bun" &&
 		step.argv[1] === "add"
 	) {
-		const r = await ctx.run([ctx.resolve("bun"), "pm", "bin", "-g"]);
-		const dir = r.exitCode === 0 ? r.outputTail.trim().split("\n").pop() : "";
-		return dir?.trim() || null;
+		const r = await ctx.run([ctx.resolve("bun"), "pm", "bin", "-g"], {
+			captureStdout: true,
+		});
+		return r.exitCode === 0 ? lastLine(r.stdout) : null;
 	}
 	return null;
 }
@@ -750,12 +926,11 @@ async function verifyInstalled(
 	}
 	const first = offPath[0];
 	if (first?.dir) {
-		const line = pathRcLine(first.dir, env.userShell);
 		return {
 			status: "off-path",
 			dir: first.dir,
 			why: `installed in ${first.dir}, which is not on the PATH Claude Code starts with`,
-			remedy: `add  ${line}  to ${rcFile(env.userShell)}, then restart Claude Code from a new terminal`,
+			remedy: pathRemedy(first.dir, env),
 		};
 	}
 	return { status: "installed" };
@@ -768,10 +943,20 @@ interface StepResult {
 	outputTail: string;
 }
 
+/** How one argv of a step runs. */
+interface RunHow {
+	/** Through sudo: SIGKILL cannot be relayed, so it gets a longer grace. */
+	escalated?: boolean;
+	/** Added to the child's environment. */
+	env?: Readonly<Record<string, string>>;
+	/** A query whose answer is its stdout: `RunResult.stdout` is set. */
+	captureStdout?: boolean;
+}
+
 interface StepContext {
 	env: PlanEnv;
 	io: ApplyIO;
-	run(argv: string[], escalated?: boolean): Promise<RunResult>;
+	run(argv: string[], how?: RunHow): Promise<RunResult>;
 	escalate(argv: string[]): string[];
 	root: boolean;
 	resolve(tool: string): string;
@@ -784,15 +969,25 @@ const fromRun = (argv: string[], r: RunResult): StepResult => ({
 	outputTail: r.spawnError ?? r.outputTail,
 });
 
+/** The last non-empty line of a query's stdout, or null. */
+function lastLine(stdout: string | undefined): string | null {
+	const line = (stdout ?? "")
+		.split("\n")
+		.map((l) => l.trim())
+		.filter(Boolean)
+		.pop();
+	return line || null;
+}
+
 /** Run argvs in order, stopping at the first that fails. */
 async function sequence(
 	ctx: StepContext,
 	argvs: string[][],
-	escalated: boolean,
+	how: RunHow = {},
 ): Promise<StepResult> {
 	let last: StepResult = { ok: true, exitCode: 0, outputTail: "" };
 	for (const argv of argvs) {
-		last = fromRun(argv, await ctx.run(argv, escalated));
+		last = fromRun(argv, await ctx.run(argv, how));
 		if (!last.ok) return last;
 	}
 	return last;
@@ -814,14 +1009,12 @@ async function runStep(
 						ctx.escalate(["apt-get", ...APT_LOCK, "update"]),
 						install,
 					],
-					ctx.root,
+					{ escalated: ctx.root },
 				);
 			}
-			return sequence(
-				ctx,
-				[ctx.escalate([ctx.resolve(tool), ...args])],
-				ctx.root,
-			);
+			return sequence(ctx, [ctx.escalate([ctx.resolve(tool), ...args])], {
+				escalated: ctx.root,
+			});
 		}
 		case "uv-module":
 			return runUvModule(step, ctx);
@@ -839,17 +1032,14 @@ async function runUvModule(
 	ctx: StepContext,
 ): Promise<StepResult> {
 	const uv = ctx.resolve("uv");
-	const sync = await sequence(
-		ctx,
-		[uvScriptArgv(["sync"], step.script, uv)],
-		false,
-	);
+	const sync = await sequence(ctx, [uvScriptArgv(["sync"], step.script, uv)]);
 	if (!sync.ok) return sync;
 	const findArgv = uvScriptArgv(["python", "find"], step.script, uv);
-	const found = await ctx.run(findArgv);
+	const found = await ctx.run(findArgv, { captureStdout: true });
 	const findResult = fromRun(findArgv, found);
 	if (!findResult.ok) return findResult;
-	const py = found.outputTail.trim().split("\n").pop()?.trim() ?? "";
+	// The interpreter is what uv prints on stdout; a warning goes to stderr.
+	const py = lastLine(found.stdout);
 	if (!py) {
 		return {
 			...findResult,
@@ -869,7 +1059,7 @@ async function runUvModule(
 	return sequence(
 		ctx,
 		[ctx.escalate([py, "-B", "-m", step.module, ...step.args])],
-		ctx.root,
+		{ escalated: ctx.root },
 	);
 }
 
@@ -882,7 +1072,9 @@ async function runBootstrap(
 	try {
 		const file = join(dir, "install.sh");
 		writeFileSync(file, body, { mode: 0o600 });
-		return await sequence(ctx, [[ctx.resolve(step.interpreter), file]], false);
+		return await sequence(ctx, [[ctx.resolve(step.interpreter), file]], {
+			...(step.env ? { env: step.env } : {}),
+		});
 	} finally {
 		rmSync(dir, { recursive: true, force: true });
 	}
@@ -919,7 +1111,7 @@ async function runRelease(
 	}
 	const dest = expandHome(step.dest, ctx.env.home);
 	mkdirSync(dest, { recursive: true });
-	const tmp = mkdtempSync(join(dest, ".magus-tmp-"));
+	const tmp = mkdtempSync(join(dest, RELEASE_TMP_PREFIX));
 	try {
 		if (step.format === "binary") {
 			// The asset is the binary: the verified bytes are the file.

package/src/services/git-worktree.ts

@@ -190,6 +190,47 @@ export async function inheritablePaths(projectPath: string): Promise<string[]> {
 	return paths;
 }
 
+/** One working tree of a repository, as `git worktree list` reports it. */
+export interface WorkingTree {
+	/** Absolute path, as git recorded it. */
+	path: string;
+	/** git says its folder is gone (`prunable`); the record outlives it. */
+	prunable: boolean;
+}
+
+/**
+ * Every working tree of `projectPath`'s repository — the main one first, then
+ * each linked worktree — and the one `projectPath` itself sits in.
+ *
+ * Null when git cannot say: not a repository, git missing or not answering.
+ * A bare repository's own record has no working tree and is left out. Reads
+ * only; never caches, because a worktree added while magus runs is exactly
+ * what a caller of this wants to see.
+ */
+export async function listWorkingTrees(
+	projectPath: string,
+): Promise<{ self: string; trees: WorkingTree[] } | null> {
+	const dir = path.resolve(projectPath);
+	const [top, list] = await Promise.all([
+		git(dir, ["rev-parse", "--show-toplevel"]),
+		git(dir, ["worktree", "list", "--porcelain"]),
+	]);
+	if (top.code !== 0 || !top.out || list.code !== 0) return null;
+	const trees: WorkingTree[] = [];
+	for (const record of list.out.split(/\n\s*\n/)) {
+		const lines = record.split("\n").map((l) => l.trim());
+		const line = lines.find((l) => l.startsWith("worktree "));
+		if (!line || lines.includes("bare")) continue;
+		trees.push({
+			path: path.resolve(line.slice("worktree ".length)),
+			prunable: lines.some(
+				(l) => l === "prunable" || l.startsWith("prunable "),
+			),
+		});
+	}
+	return { self: path.resolve(top.out), trees };
+}
+
 async function resolveInheritable(
 	dir: string,
 ): Promise<{ paths: string[]; answered: boolean }> {

package/src/services/plugin-mcp-config.ts

@@ -217,7 +217,9 @@ export async function getPluginSourcePath(
 				const plugin = manifest.plugins.find(
 					(p: { name: string }) => p.name === pluginName,
 				);
-				return plugin?.source;
+				// An object source (git-subdir, github, url) is fetched from its own
+				// repo, not read from the marketplace clone, so there is no local path.
+				return typeof plugin?.source === "string" ? plugin.source : undefined;
 			}
 		}
 	} catch {