magus-cli 7.7.0 → 7.9.0

package/src/utils/run.ts

@@ -1,67 +1,138 @@
 /**
- * Running an installer, with the shell split out from the argv.
+ * The one way magus runs an installer or any other child process it waits on.
  *
- * 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.
+ * Lives in `utils/` rather than `cli/` because services need it and a service
+ * must not import from a front end — `cli/` and `ui/` are sibling front ends
+ * over `services/`.
  *
- * 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".
+ * Contract:
+ *
+ *  - **argv only.** No `shell` option: `cmd` is resolved on PATH as an
+ *    executable, and every argument stays exactly one argument. Package names
+ *    reach here from `.claude/profiles.json` and plugin `requires` — committed
+ *    by teammates, fetched from marketplaces — so under a shell a space or a
+ *    `$(…)` in one of them would execute.
+ *  - **Never writes to the terminal.** stdin is ignored and stdout/stderr are
+ *    piped and captured; what (if anything) is shown, and where, is the
+ *    caller's decision through `onOutput`. The guarantee is exactly this: a
+ *    child cannot read the terminal through its stdin. A child that opens
+ *    `/dev/tty` itself still can; it keeps magus's controlling terminal and
+ *    session on purpose, so a `sudo -v` ticket stays usable by `sudo -n`.
+ *  - **Bounded.** At `timeoutMs` the child gets SIGTERM, then SIGKILL after
+ *    `killGraceMs` (5 s by default; a `sudo` step passes more, because SIGKILL
+ *    to `sudo` cannot be relayed and would orphan its root child).
  */
 
 import { spawn } from "node:child_process";
 import type { Command } from "./command-utils.js";
+import { stripAnsi } from "./string-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> {
+/** How much combined output a {@link RunResult} keeps: the last 16 KiB. */
+export const OUTPUT_TAIL_BYTES = 16 * 1024;
+
+const DEFAULT_KILL_GRACE_MS = 5_000;
+
+export interface RunResult {
+	/** null when killed by a signal or never spawned. */
+	exitCode: number | null;
+	signal: string | null;
+	timedOut: boolean;
+	/** Set when the process could not be started (ENOENT, EACCES, …). */
+	spawnError?: string;
+	/** Combined stdout + stderr, last {@link OUTPUT_TAIL_BYTES}, ANSI stripped. */
+	outputTail: string;
+	durationMs: number;
+}
+
+export interface RunOptions {
+	timeoutMs: number;
+	/** Replaces the child's environment when given. */
+	env?: Record<string, string | undefined>;
+	cwd?: string;
+	/** Between SIGTERM and SIGKILL once `timeoutMs` passes. */
+	killGraceMs?: number;
+	/** Each output chunk as it arrives, ANSI intact. Never called after return. */
+	onOutput?: (chunk: string) => void;
+}
+
+/** Keep the last {@link OUTPUT_TAIL_BYTES} of a growing buffer. */
+function tail(text: string): string {
+	const bytes = Buffer.from(text, "utf8");
+	if (bytes.length <= OUTPUT_TAIL_BYTES) return text;
+	return bytes.subarray(bytes.length - OUTPUT_TAIL_BYTES).toString("utf8");
+}
+
+/** Run `c` as argv and capture it; resolves when it exits or is killed. */
+export function runArgv(c: Command, opts: RunOptions): Promise<RunResult> {
+	const started = Date.now();
 	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));
+		let output = "";
+		let timedOut = false;
+		let settled = false;
+		let killTimer: ReturnType<typeof setTimeout> | undefined;
+		const finish = (result: Omit<RunResult, "outputTail" | "durationMs">) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			if (killTimer) clearTimeout(killTimer);
+			resolve({
+				...result,
+				outputTail: stripAnsi(tail(output)),
+				durationMs: Date.now() - started,
+			});
+		};
+		const child = spawn(c.cmd, [...c.args], {
+			stdio: ["ignore", "pipe", "pipe"],
+			...(opts.env ? { env: opts.env } : {}),
+			...(opts.cwd ? { cwd: opts.cwd } : {}),
+		});
+		const onData = (data: Buffer) => {
+			const chunk = data.toString("utf8");
+			output = tail(output + chunk);
+			if (!settled) opts.onOutput?.(chunk);
+		};
+		child.stdout?.on("data", onData);
+		child.stderr?.on("data", onData);
+		const timer = setTimeout(() => {
+			timedOut = true;
+			child.kill("SIGTERM");
+			killTimer = setTimeout(
+				() => child.kill("SIGKILL"),
+				opts.killGraceMs ?? DEFAULT_KILL_GRACE_MS,
+			);
+		}, opts.timeoutMs);
+		child.on("error", (error) =>
+			finish({
+				exitCode: null,
+				signal: null,
+				timedOut,
+				spawnError: error.message,
+			}),
+		);
+		child.on("close", (code, signal) =>
+			finish({ exitCode: code, signal, timedOut }),
+		);
 	});
 }
 
+/** True when the run exited 0 (and was neither killed nor unstartable). */
+export function succeeded(r: RunResult): boolean {
+	return r.exitCode === 0 && !r.timedOut && r.spawnError === undefined;
+}
+
 /**
- * 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.
+ * One line saying why a run did not succeed, for a failure report. The output
+ * tail's last non-empty line is the installer's own reason more often than not.
  */
-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));
-	});
+export function runFailureReason(r: RunResult): string {
+	if (r.spawnError) return r.spawnError;
+	if (r.timedOut) return `timed out after ${Math.round(r.durationMs / 1000)}s`;
+	const last = r.outputTail
+		.split("\n")
+		.map((l) => l.trim())
+		.filter(Boolean)
+		.pop();
+	const code =
+		r.exitCode !== null ? `exit ${r.exitCode}` : `killed by ${r.signal}`;
+	return last ? `${code}: ${last}` : code;
 }

package/src/utils/string-utils.ts

@@ -86,3 +86,12 @@ export function parsePluginId(pluginId: string): ParsedPluginId | null {
 		raw: trimmed,
 	};
 }
+
+/** Every CSI sequence, not only SGR — the live region emits cursor moves too. */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: ESC is the thing being matched.
+export const CSI = /\x1b\[[0-9;?]*[\x20-\x2f]*[\x40-\x7e]/g;
+
+/** `text` without its ANSI CSI sequences. */
+export function stripAnsi(text: string): string {
+	return text.replace(CSI, "");
+}

package/src/utils/user-path.ts

@@ -0,0 +1,60 @@
+/**
+ * A file as the user names it, never as an absolute path.
+ *
+ * magus names a file only when the user must act on it (fix it by hand,
+ * commit it), and then in the words they would type: `~/.claude/settings.json`
+ * for their own settings, `.claude/settings.json` for this project's. The
+ * absolute path is where this machine keeps it — the mechanism, and noise
+ * that pushes the actual problem off the end of the line.
+ */
+
+import os from "node:os";
+import path from "node:path";
+
+/** `true` when `file` is `dir` itself or inside it. */
+function isInside(file: string, dir: string): boolean {
+	const rel = path.relative(dir, file);
+	return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+/**
+ * `file` in the user's terms:
+ *
+ *  1. Under the user's own `~/.claude/` → `~/.claude/…` (their USER settings),
+ *     checked first so a project opened at the home folder still names it so.
+ *  2. Under the project folder → relative to it: `.claude/settings.json`.
+ *  3. Anywhere else with a `.claude/` folder in its path → from that folder
+ *     on, which is how the user knows a project's settings file.
+ *  4. Under the home folder → `~/…`.
+ *  5. Otherwise its name alone.
+ */
+export function userFacingPath(
+	file: string,
+	projectDir: string = process.cwd(),
+	home: string = os.homedir(),
+): string {
+	const abs = path.resolve(file);
+	const userClaude = home ? path.join(home, ".claude") : "";
+	if (userClaude && isInside(abs, userClaude)) {
+		return `~/${path.relative(home, abs)}`;
+	}
+	if (projectDir && isInside(abs, path.resolve(projectDir))) {
+		const rel = path.relative(path.resolve(projectDir), abs);
+		if (rel) return rel;
+	}
+	const marker = `${path.sep}.claude${path.sep}`;
+	const at = abs.lastIndexOf(marker);
+	if (at >= 0) return abs.slice(at + 1);
+	if (home && isInside(abs, home)) return `~/${path.relative(home, abs)}`;
+	return path.basename(abs);
+}
+
+/** Every occurrence of `file`'s absolute path in `text`, in the user's terms. */
+export function withUserFacingPath(
+	text: string,
+	file: string,
+	projectDir?: string,
+	home?: string,
+): string {
+	return text.split(file).join(userFacingPath(file, projectDir, home));
+}

package/src/__tests__/go-module.test.ts

@@ -1,43 +0,0 @@
-/**
- * goBinaryName: the one rule for turning a Go module path into the binary
- * `go install` produces. Both consumers (plugin-setup's Go path and
- * plugin-requires' `setup.go` branch) are tested through their own surfaces;
- * this file pins the rule itself.
- */
-
-import { describe, expect, test } from "bun:test";
-import { goBinaryName } from "../utils/go-module.js";
-
-describe("goBinaryName", () => {
-	test("takes the last segment of a v0/v1 module path", () => {
-		expect(goBinaryName("github.com/MadAppGang/tmux-mcp")).toBe("tmux-mcp");
-	});
-
-	test("strips a trailing /v2 major-version suffix before taking the name", () => {
-		expect(goBinaryName("github.com/MadAppGang/tmux-mcp/v2")).toBe("tmux-mcp");
-	});
-
-	test("strips multi-digit suffixes (/v10, /v42)", () => {
-		expect(goBinaryName("github.com/x/tool/v10")).toBe("tool");
-		expect(goBinaryName("github.com/x/tool/v42")).toBe("tool");
-	});
-
-	test("a segment that merely starts with v2 is a name, not a suffix", () => {
-		expect(goBinaryName("github.com/x/v2tool")).toBe("v2tool");
-	});
-
-	test("v0 and v1 are never path suffixes, so they stay as names", () => {
-		// Nobody names a binary this, but the rule must not invent an exception.
-		expect(goBinaryName("github.com/x/v1")).toBe("v1");
-		expect(goBinaryName("github.com/x/v0")).toBe("v0");
-	});
-
-	test("a suffix in the middle of the path is not trailing and is kept", () => {
-		expect(goBinaryName("github.com/x/repo/v2/cmd/cli")).toBe("cli");
-	});
-
-	test("single-segment and empty inputs pass through", () => {
-		expect(goBinaryName("mytool")).toBe("mytool");
-		expect(goBinaryName("")).toBe("");
-	});
-});