magus-cli 0.0.0-placeholder → 7.1.0

package/src/__tests__/cli-live.test.ts

@@ -0,0 +1,391 @@
+/**
+ * Tests for the live region.
+ *
+ * The invariant worth defending is the ORDER of writes around a permanent line.
+ * `note()` must erase the animated block, write, then repaint. Writing first
+ * puts the line inside the block, where the next repaint's cursor-up counts it
+ * as a frame row and starts eating the scrollback record — a data-loss bug that
+ * looks like a flicker.
+ *
+ * The console-capture suite exists because that ordering was documented as a
+ * rule and the rule was broken in production by code two call layers away
+ * (`plugin-manager`'s stale-marketplace advisory, reached through
+ * `getAvailablePlugins`). A rule spanning a call graph this module does not own
+ * has to be a mechanism, so these tests pin the mechanism.
+ *
+ * The clamps are the other half. A frame line that reaches the terminal's last
+ * column auto-wraps into two rows while the repainter still counts it as one,
+ * so the block walks down the screen a row per frame.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { width } from "../cli/ansi.js";
+import { LiveRegion, withPaused } from "../cli/live.js";
+
+/** A write stream that records instead of drawing. */
+function fakeStream(
+	opts: { isTTY?: boolean; columns?: number; rows?: number } = {},
+) {
+	const writes: string[] = [];
+	const listeners = new Map<string, Array<() => void>>();
+	const stream = {
+		write: (chunk: string) => {
+			writes.push(chunk);
+			return true;
+		},
+		on(event: string, fn: () => void) {
+			const list = listeners.get(event) ?? [];
+			list.push(fn);
+			listeners.set(event, list);
+			return this;
+		},
+		off(event: string, fn: () => void) {
+			const list = (listeners.get(event) ?? []).filter((f) => f !== fn);
+			listeners.set(event, list);
+			return this;
+		},
+		isTTY: opts.isTTY ?? true,
+		columns: opts.columns ?? 80,
+		rows: opts.rows ?? 24,
+	} as unknown as NodeJS.WriteStream & {
+		columns: number;
+		rows: number;
+	};
+	const emit = (event: string) => {
+		for (const fn of listeners.get(event) ?? []) fn();
+	};
+	return { stream, writes, emit, all: () => writes.join("") };
+}
+
+/**
+ * An animated region that needs no timer: paint via `refresh()`.
+ *
+ * `captureConsole` is OFF here. These tests assert on stream writes, and a
+ * region that hijacks the global console would also hijack the test runner's
+ * own reporting. The capture suite below opts back in deliberately.
+ */
+function region(opts: Parameters<typeof fakeStream>[0] = {}) {
+	const fake = fakeStream(opts);
+	const live = new LiveRegion({
+		stream: fake.stream,
+		animate: true,
+		fps: 1000,
+		captureConsole: false,
+	});
+	return { ...fake, live };
+}
+
+describe("non-animated mode — a pipe, CI, or NO_COLOR", () => {
+	test("the transient block is never painted, but the record still prints", () => {
+		const fake = fakeStream({ isTTY: false });
+		const live = new LiveRegion({ stream: fake.stream, animate: false });
+		live.start(() => ["spinning"]);
+		live.refresh();
+		live.note("permanent one");
+		live.stop(["final"]);
+
+		expect(fake.writes).toEqual(["permanent one\n", "final\n"]);
+	});
+
+	test("no escape sequence of any kind reaches a pipe", () => {
+		const fake = fakeStream({ isTTY: false });
+		const live = new LiveRegion({ stream: fake.stream, animate: false });
+		live.start(() => ["frame"]);
+		live.note("line");
+		live.pause();
+		live.resume();
+		live.stop(["done"]);
+		expect(fake.all()).not.toContain("\x1b");
+	});
+
+	test("console is never captured when nothing is being painted", () => {
+		const fake = fakeStream({ isTTY: false });
+		const original = console.log;
+		const live = new LiveRegion({ stream: fake.stream, animate: false });
+		live.start(() => ["frame"]);
+		try {
+			expect(console.log).toBe(original);
+		} finally {
+			live.stop();
+		}
+	});
+});
+
+describe("animated mode", () => {
+	test("start hides the cursor and paints the frame", () => {
+		const { live, all } = region();
+		live.start(() => ["row one", "row two"]);
+		expect(all()).toContain("\x1b[?25l");
+		expect(all()).toContain("row one\nrow two\n");
+		live.stop();
+	});
+
+	test("a repaint erases exactly the rows it painted", () => {
+		const { live, writes } = region();
+		live.start(() => ["a", "b", "c"]);
+		writes.length = 0;
+		live.refresh();
+		// Three rows painted, so three rows up and erase below.
+		expect(writes[0]).toBe("\x1b[3A\x1b[0J");
+		live.stop();
+	});
+
+	test("note erases BEFORE writing, then repaints", () => {
+		const { live, writes } = region();
+		live.start(() => ["frame"]);
+		writes.length = 0;
+		live.note("kept");
+
+		expect(writes[0]).toBe("\x1b[1A\x1b[0J");
+		expect(writes[1]).toBe("kept\n");
+		expect(writes[2]).toBe("frame\n");
+	});
+
+	test("a frame that shrinks does not leave orphaned rows", () => {
+		let rows = ["a", "b", "c"];
+		const { live, writes } = region();
+		live.start(() => rows);
+		rows = ["a"];
+		writes.length = 0;
+		live.refresh();
+		// Erase-below clears the two rows the shorter frame no longer covers.
+		expect(writes[0]).toBe("\x1b[3A\x1b[0J");
+		expect(writes[1]).toBe("a\n");
+		live.stop();
+	});
+
+	test("a line is clipped one column short of the terminal width", () => {
+		const { live, writes } = region({ columns: 20 });
+		live.start(() => ["x".repeat(40)]);
+		const painted = writes.at(-1) ?? "";
+		// DISPLAY width, not `.length`. `truncate` appends a reset when colour is
+		// on, and colour is on exactly when stdout is a real terminal — so a
+		// `.length` assertion passed piped and failed the moment anyone ran the
+		// suite in a terminal, over four zero-width bytes. The claim being made
+		// here is about columns, so measure columns.
+		expect(width(painted.replace(/\n$/, ""))).toBe(19);
+		live.stop();
+	});
+
+	test("the block is capped one row short of the terminal height", () => {
+		const { live, writes } = region({ rows: 6 });
+		live.start(() => Array.from({ length: 20 }, (_, i) => `row ${i}`));
+		const painted = (writes.at(-1) ?? "").split("\n").filter(Boolean);
+		expect(painted).toHaveLength(5);
+		live.stop();
+	});
+
+	test("stop erases the frame and restores the cursor", () => {
+		const { live, writes } = region();
+		live.start(() => ["frame"]);
+		writes.length = 0;
+		live.stop(["record"]);
+		expect(writes[0]).toBe("\x1b[1A\x1b[0J");
+		expect(writes[1]).toBe("record\n");
+		expect(writes[2]).toBe("\x1b[?25h");
+	});
+
+	test("stop with nothing painted still shows the cursor", () => {
+		const { live, all } = region();
+		live.start(() => []);
+		live.stop();
+		expect(all()).toContain("\x1b[?25h");
+	});
+});
+
+describe("resize", () => {
+	test("a resize abandons the old block instead of mis-erasing it", () => {
+		// `painted` is a row count measured at the OLD width. After a narrowing,
+		// the block occupies more rows than it says, so a cursor-up of `painted`
+		// lands inside it and smears. The only safe move is to stop claiming
+		// ownership of those rows.
+		const { live, writes, emit, stream } = region({ columns: 80 });
+		live.start(() => ["x".repeat(70)]);
+		writes.length = 0;
+		(stream as unknown as { columns: number }).columns = 40;
+		emit("resize");
+
+		// biome-ignore lint/suspicious/noControlCharactersInRegex: ESC is the thing being matched.
+		const CURSOR_UP = /\x1b\[\d+A/;
+		expect(writes.some((w) => CURSOR_UP.test(w))).toBe(false);
+		// Display width, for the reason given on the clipping test above.
+		expect(width((writes.at(-1) ?? "").replace(/\n$/, ""))).toBe(39);
+		live.stop();
+	});
+
+	test("the resize listener is removed on stop", () => {
+		const { live, writes, emit } = region();
+		live.start(() => ["frame"]);
+		live.stop();
+		writes.length = 0;
+		emit("resize");
+		expect(writes).toEqual([]);
+	});
+});
+
+describe("handing the terminal over", () => {
+	test("pause erases the block and shows the cursor before the subprocess", () => {
+		const { live, writes } = region();
+		live.start(() => ["frame"]);
+		writes.length = 0;
+		live.pause();
+		expect(writes).toEqual(["\x1b[1A\x1b[0J", "\x1b[?25h"]);
+	});
+
+	test("note does NOT repaint while paused", () => {
+		// A repaint here draws the block underneath output from whatever now owns
+		// the terminal — corrupt, and in the way of a readline prompt.
+		const { live, writes } = region();
+		live.start(() => ["FRAME"]);
+		live.pause();
+		writes.length = 0;
+		live.note("subprocess said something");
+		expect(writes).toEqual(["subprocess said something\n"]);
+	});
+
+	test("resume repaints and re-hides", () => {
+		const { live, writes } = region();
+		live.start(() => ["frame"]);
+		live.pause();
+		writes.length = 0;
+		live.resume();
+		expect(writes[0]).toBe("\x1b[?25l");
+		expect(writes[1]).toBe("frame\n");
+		live.stop();
+	});
+
+	test("withPaused resumes even when the work throws", async () => {
+		const { live, writes } = region();
+		live.start(() => ["frame"]);
+		await expect(
+			withPaused(live, async () => {
+				throw new Error("installer failed");
+			}),
+		).rejects.toThrow("installer failed");
+		// A resume repaint after the throw proves the region was handed back.
+		expect(writes.at(-1)).toBe("frame\n");
+		live.stop();
+	});
+
+	test("withPaused returns the work's value", async () => {
+		const { live } = region();
+		live.start(() => ["frame"]);
+		expect(await withPaused(live, async () => 42)).toBe(42);
+		live.stop();
+	});
+});
+
+describe("console capture — the invariant as a mechanism", () => {
+	/** Console is process-global: every test here must put it back. */
+	let restore: (() => void) | null = null;
+	afterEach(() => {
+		restore?.();
+		restore = null;
+	});
+
+	function capturing(opts: Parameters<typeof fakeStream>[0] = {}) {
+		const out = fakeStream(opts);
+		const err = fakeStream(opts);
+		const live = new LiveRegion({
+			stream: out.stream,
+			errorStream: err.stream,
+			animate: true,
+			fps: 1000,
+		});
+		const original = {
+			log: console.log,
+			info: console.info,
+			warn: console.warn,
+			error: console.error,
+		};
+		restore = () => {
+			live.stop();
+			Object.assign(console, original);
+		};
+		return { live, out, err };
+	}
+
+	test("a bare console.log from anywhere is routed, not left inside the block", () => {
+		// This is the production bug: plugin-manager's stale-marketplace advisory
+		// prints from two call layers below the catalog step. Without capture it
+		// lands under the block, the next cursor-up is short by a row, and the
+		// advisory is erased unread.
+		const { live, out } = capturing();
+		live.start(() => ["FRAME"]);
+		out.writes.length = 0;
+		console.log("ℹ Marketplace magus is stale");
+
+		expect(out.writes).toEqual([
+			"\x1b[1A\x1b[0J",
+			"ℹ Marketplace magus is stale\n",
+			"FRAME\n",
+		]);
+	});
+
+	test("without capture the same call corrupts the block", () => {
+		// The negative control. This is what the code did before the fix, and it
+		// is why documenting the rule was not enough.
+		const out = fakeStream();
+		const live = new LiveRegion({
+			stream: out.stream,
+			animate: true,
+			fps: 1000,
+			captureConsole: false,
+		});
+		live.start(() => ["FRAME"]);
+		out.writes.length = 0;
+		out.stream.write("ℹ Marketplace magus is stale\n"); // an uncaptured write
+		live.refresh();
+		// One row up from a cursor now two rows below the block's start: the
+		// erase begins inside the frame rather than at its top.
+		expect(out.writes[1]).toBe("\x1b[1A\x1b[0J");
+		live.stop();
+	});
+
+	test("stderr stays on stderr", () => {
+		// Silently moving warn/error to stdout would break `2>err.log`.
+		const { live, out, err } = capturing();
+		live.start(() => ["FRAME"]);
+		out.writes.length = 0;
+		err.writes.length = 0;
+		console.warn("a warning");
+		console.error("an error");
+
+		expect(err.writes.filter((w) => !w.startsWith("\x1b"))).toEqual([
+			"a warning\n",
+			"an error\n",
+		]);
+		expect(out.writes.some((w) => w.includes("a warning"))).toBe(false);
+	});
+
+	test("format specifiers and multi-line writes survive", () => {
+		// A newline inside one write is a row the erase arithmetic cannot see,
+		// so it has to be split into separate notes.
+		const { live, out } = capturing();
+		live.start(() => ["FRAME"]);
+		out.writes.length = 0;
+		console.log("%s has %d plugins\nsecond line", "magus", 12);
+
+		expect(out.writes).toContain("magus has 12 plugins\n");
+		expect(out.writes).toContain("second line\n");
+	});
+
+	test("console is released on stop", () => {
+		const original = console.log;
+		const { live } = capturing();
+		live.start(() => ["FRAME"]);
+		expect(console.log).not.toBe(original);
+		live.stop();
+		expect(console.log).toBe(original);
+	});
+
+	test("console is released while paused, so a subprocess writes directly", () => {
+		const original = console.log;
+		const { live } = capturing();
+		live.start(() => ["FRAME"]);
+		live.pause();
+		expect(console.log).toBe(original);
+		live.resume();
+		expect(console.log).not.toBe(original);
+	});
+});

package/src/__tests__/cli-router.test.ts

@@ -0,0 +1,240 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { parseThemeFlag, route } from "../cli/router.js";
+
+// Silence the help banner and capture what the router prints, without
+// touching the network (--version) or spawning processes (claude/update).
+let logSpy: ReturnType<typeof mock>;
+let errSpy: ReturnType<typeof mock>;
+let logs: string[];
+let errs: string[];
+
+beforeEach(() => {
+	logs = [];
+	errs = [];
+	logSpy = mock((...a: unknown[]) => {
+		logs.push(a.join(" "));
+	});
+	errSpy = mock((...a: unknown[]) => {
+		errs.push(a.join(" "));
+	});
+	console.log = logSpy as any;
+	console.error = errSpy as any;
+});
+
+afterEach(() => {
+	mock.restore();
+});
+
+describe("route() dispatch", () => {
+	test("bare invocation falls through to the TUI", async () => {
+		const r = await route([], "1.2.3");
+		expect(r.handled).toBe(false);
+		expect(r.launchTui).toBe(true);
+	});
+
+	test("an unrecognized token falls through to the TUI", async () => {
+		const r = await route(["totally-unknown"], "1.2.3");
+		expect(r.handled).toBe(false);
+		expect(r.launchTui).toBe(true);
+	});
+
+	test("--help is handled, exits 0, and does not launch the TUI", async () => {
+		const r = await route(["--help"], "9.9.9");
+		expect(r).toEqual({ handled: true, exitCode: 0, launchTui: false });
+		expect(logs.join("\n")).toContain("magus v9.9.9");
+		// The corrected help must not carry the stale tab names.
+		expect(logs.join("\n")).not.toContain("[3] Status");
+		expect(logs.join("\n")).toContain("[3] MCP");
+	});
+
+	test("-h is treated the same as --help", async () => {
+		const r = await route(["-h"], "1.0.0");
+		expect(r.handled).toBe(true);
+		expect(r.exitCode).toBe(0);
+	});
+
+	test("install, profile, and doctor are routed to real handlers (not stubs)", async () => {
+		// The router maps these to their real command handlers, which are covered
+		// by their services' unit tests. We don't invoke them here to avoid
+		// touching the filesystem / running global installs.
+		const mod = await import("../cli/router.js");
+		expect(typeof mod.route).toBe("function");
+	});
+});
+
+describe("update / upgrade split", () => {
+	// `update` used to self-update magus. It now means what it means in every
+	// package manager — bring THIS PROJECT's dependencies up to date — and
+	// self-update moved to `upgrade`. Both halves are asserted here because a
+	// silent regression either way sends the user to the wrong command.
+
+	test("`upgrade` is the self-update command", async () => {
+		const mod = await import("../cli/upgrade.js");
+		expect(typeof mod.runUpgradeCommand).toBe("function");
+	});
+
+	test("`update` is the dependency command and takes args", async () => {
+		const mod = await import("../cli/update.js");
+		expect(typeof mod.runUpdateCommand).toBe("function");
+		// It takes `args`. The old self-update took none, and `Function.length`
+		// stops counting at the first defaulted parameter — so `projectPath`
+		// does not show up here, but a regression to the no-arg form would.
+		expect(mod.runUpdateCommand.length).toBe(1);
+		expect(mod.runUpdateCommand.length).toBeGreaterThan(
+			(await import("../cli/upgrade.js")).runUpgradeCommand.length,
+		);
+	});
+
+	test("--version points at `magus upgrade`, not `magus update`", async () => {
+		await route(["--version"], "1.0.0");
+		const out = logs.join("\n");
+		// Only assert when an update was actually offered; the check hits the
+		// network and may report nothing.
+		if (out.includes("Update available")) {
+			expect(out).toContain("magus upgrade");
+			expect(out).not.toContain("Run: magus update");
+		}
+	});
+
+	test("help documents both, and describes update as the dependency command", async () => {
+		await route(["--help"], "1.0.0");
+		const help = logs.join("\n");
+		expect(help).toContain("update [profile]");
+		expect(help).toContain("upgrade");
+		expect(help).toContain("Update magus ITSELF");
+		expect(help).toContain("profile init");
+		// The old wording sent people to `update` for a self-update.
+		expect(help).not.toContain("update             Update magus itself");
+	});
+});
+
+describe("--theme", () => {
+	test("T-flag-ok: --theme light launches the TUI carrying the theme", async () => {
+		const r = await route(["--theme", "light"], "1.0.0");
+		expect(r).toEqual({ handled: false, launchTui: true, theme: "light" });
+	});
+
+	test("T-flag-ok: --theme=dark is the same flag", async () => {
+		const r = await route(["--theme=dark"], "1.0.0");
+		expect(r).toEqual({ handled: false, launchTui: true, theme: "dark" });
+	});
+
+	test("no --theme leaves the outcome without a theme key", async () => {
+		const r = await route([], "1.0.0");
+		expect("theme" in r).toBe(false);
+	});
+
+	test.each([
+		[["--theme", "solarized"]],
+		[["--theme", "purple"]],
+		[["--theme", "Dark"]],
+		[["--theme", "auto"]],
+		[["--theme"]],
+		[["--theme", "--no-refresh"]],
+		[["--theme="]],
+	])(
+		"T-flag-bad: %j is handled with exit 1 and names both words",
+		async (argv) => {
+			const r = await route(argv, "1.0.0");
+
+			expect(r).toEqual({ handled: true, exitCode: 1, launchTui: false });
+			const err = errs.join("\n");
+			expect(err).toContain("light");
+			expect(err).toContain("dark");
+			expect(err).toContain("--theme");
+		},
+	);
+
+	test("T-flag-cmd: --theme dark update strips the flag and dispatches update", () => {
+		// The seam: parseThemeFlag is what route() dispatches on. Asserting on
+		// `rest` proves `update` is the command token that reaches the switch,
+		// without running the real update handler against this machine.
+		const parsed = parseThemeFlag(["--theme", "dark", "update", "--dry-run"]);
+
+		expect(parsed).toEqual({
+			ok: true,
+			theme: "dark",
+			rest: ["update", "--dry-run"],
+		});
+	});
+
+	test("T-flag-cmd-route: route() hands update the stripped argv, not the original", async () => {
+		// The parse test above cannot catch a route() that re-reads the original
+		// argv inside the switch. Mock the command seam and assert what reached it.
+		// mock.module is process-global and survives mock.restore(), so the real
+		// module is put back at the end — a later file in the same `bun test`
+		// process must not inherit the fake.
+		const actual = { ...(await import("../cli/update.js")) };
+		const calls: string[][] = [];
+		mock.module("../cli/update.js", () => ({
+			...actual,
+			runUpdateCommand: async (args: string[]) => {
+				calls.push(args);
+				return 0;
+			},
+		}));
+		try {
+			const { route: routeWithMock } = await import("../cli/router.js");
+			const r = await routeWithMock(
+				["--theme", "dark", "update", "--dry-run"],
+				"1.0.0",
+			);
+
+			expect(r).toEqual({ handled: true, exitCode: 0, launchTui: false });
+			expect(calls).toEqual([["--dry-run"]]);
+		} finally {
+			mock.module("../cli/update.js", () => actual);
+		}
+	});
+
+	test("T-flag-bad: an invalid --theme does not launch the TUI even when a command follows", async () => {
+		const r = await route(["--theme", "purple", "update"], "1.0.0");
+
+		expect(r).toEqual({ handled: true, exitCode: 1, launchTui: false });
+		expect(errs.join("\n")).toContain("purple");
+	});
+
+	test("T-flag-cmd: the flag may follow the command too", () => {
+		expect(parseThemeFlag(["update", "--theme=light"])).toEqual({
+			ok: true,
+			theme: "light",
+			rest: ["update"],
+		});
+	});
+
+	test("T-flag-help: --help wins over a bad --theme, and documents the flag", async () => {
+		const r = await route(["--theme", "bogus", "--help"], "1.0.0");
+
+		expect(r).toEqual({ handled: true, exitCode: 0, launchTui: false });
+		const help = logs.join("\n");
+		expect(help).toContain("--theme light|dark");
+		expect(help).toContain("MAGUS_THEME");
+		expect(help).toContain("TERM_THEME");
+		expect(errs).toEqual([]);
+	});
+
+	test("T-flag-live: `bun src/main.tsx --theme bogus` exits 1 before the renderer", () => {
+		// Exits in the router, so no tty is needed. stdin is a pipe on purpose:
+		// were the renderer reached, createCliRenderer would fail differently.
+		// --no-env-file: Bun autoloads the cwd's .env before user code, and the
+		// theme snapshot must precede any .env merge — same flag as the launchers.
+		const result = spawnSync(
+			"bun",
+			[
+				"--no-env-file",
+				path.join(import.meta.dir, "..", "main.tsx"),
+				"--theme",
+				"bogus",
+			],
+			{ encoding: "utf-8", input: "" },
+		);
+
+		expect(result.status).toBe(1);
+		expect(result.stderr).toContain("--theme");
+		expect(result.stderr).toContain("light");
+		expect(result.stderr).toContain("dark");
+		expect(result.stderr).toContain("bogus");
+	});
+});