magus-cli 7.3.1 → 7.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magus-cli",
-  "version": "7.3.1",
+  "version": "7.4.1",
   "description": "TUI tool for managing Claude Code plugins, MCPs, and configuration",
   "type": "module",
   "main": "src/main.tsx",
@@ -64,8 +64,8 @@
     "typescript": "^5.6.3"
   },
   "optionalDependencies": {
-    "magus-cli-darwin-arm64": "7.3.1",
-    "magus-cli-darwin-x64": "7.3.1",
-    "magus-cli-linux-x64": "7.3.1"
+    "magus-cli-darwin-arm64": "7.4.1",
+    "magus-cli-darwin-x64": "7.4.1",
+    "magus-cli-linux-x64": "7.4.1"
   }
 }

package/src/__tests__/blind/c1-npm-package.test.ts

@@ -0,0 +1,206 @@
+/**
+ * Blind tests — contract C1 (requirements R1.1, R1.3, R1.4, R1.5).
+ *
+ * Written from requirements.md and architecture.md only. No implementation
+ * file was read. Modules are loaded with a dynamic import inside each test, so
+ * a module that does not exist yet fails its own tests one by one instead of
+ * failing the whole file at load time.
+ *
+ * In-process: only pure contract values — MAGUS_NPM_PACKAGE, selfUpgradeCommand()
+ * (returns a command, runs nothing) and the cliTools constant.
+ *
+ * Child process: checkForUpdates does I/O (network, and possibly a cache under
+ * the home dir). Under Bun a runtime HOME change does not move os.homedir(),
+ * so it runs in a child `bun` with a temp HOME (see ./child-run.ts), with the
+ * fetch mock installed in the child before the module is imported. The child
+ * reports only the URLs it was asked for.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { runInChild } from "./child-run.js";
+
+const PACKAGE_JSON = path.resolve(import.meta.dir, "../../../package.json");
+const VERSION_CHECK_MODULE = path.resolve(
+	import.meta.dir,
+	"../../services/version-check.ts",
+);
+const REGISTRY_URL = "https://registry.npmjs.org/magus-cli/latest";
+const T = 30_000; // per-test timeout for tests that spawn a child bun
+
+/** Matches a bare `magus` package token, but not `magus-cli`. */
+const BARE_MAGUS = /(?<![\w-])magus(?![\w-])/;
+
+const loadNpmPackage = () => import("../../data/npm-package.js");
+const loadUpgrade = () => import("../../cli/upgrade.js");
+const loadCliTools = () => import("../../data/cli-tools.js");
+
+const dirs: string[] = [];
+afterEach(() => {
+	for (const dir of dirs.splice(0))
+		rmSync(dir, { recursive: true, force: true });
+});
+
+function tempDir(tag: string): string {
+	const dir = mkdtempSync(path.join(os.tmpdir(), `magus-blind-c1-${tag}-`));
+	dirs.push(dir);
+	return dir;
+}
+
+/** Installed in the child before version-check is imported. */
+const FETCH_MOCK = `
+const requested = [];
+const toUrl = (i) => typeof i === "string" ? i : i instanceof URL ? i.href : (i && i.url) || String(i);
+globalThis.fetch = async (input) => {
+	requested.push(toUrl(input));
+	return new Response(JSON.stringify({ name: "magus-cli", version: "99.0.0" }), {
+		status: 200,
+		headers: { "content-type": "application/json" },
+	});
+};
+`;
+
+/** Calls checkForUpdates(true); reports the URLs requested and whether it threw (by class only). */
+const FORCED_CHECK = `
+try {
+	await mod.checkForUpdates(true);
+	await out({ stage: "done", ok: true, requested });
+} catch (e) {
+	await out({ stage: "done", ok: false, name: (e && e.name) || typeof e, requested });
+}
+`;
+
+function forcedCheckUrls(): string[] {
+	const r = runInChild({
+		home: tempDir("home"),
+		cwd: tempDir("cwd"),
+		module: VERSION_CHECK_MODULE,
+		setup: FETCH_MOCK,
+		body: FORCED_CHECK,
+	});
+	expect(r).toMatchObject({ stage: "done" });
+	return r.requested as string[];
+}
+
+describe("C1 — the npm package name is magus-cli, defined once", () => {
+	test("R1.5 control: tools/magus/package.json names the package magus-cli", () => {
+		const pkg = JSON.parse(readFileSync(PACKAGE_JSON, "utf8"));
+		expect(pkg.name).toBe("magus-cli");
+	});
+
+	test("R1.5 MAGUS_NPM_PACKAGE is magus-cli", async () => {
+		const { MAGUS_NPM_PACKAGE } = await loadNpmPackage();
+		expect(MAGUS_NPM_PACKAGE).toBe("magus-cli");
+	});
+
+	test("R1.5 MAGUS_NPM_PACKAGE equals the name field of tools/magus/package.json", async () => {
+		const { MAGUS_NPM_PACKAGE } = await loadNpmPackage();
+		const pkg = JSON.parse(readFileSync(PACKAGE_JSON, "utf8"));
+		expect(MAGUS_NPM_PACKAGE).toBe(pkg.name);
+	});
+});
+
+describe("C1 — magus upgrade installs magus-cli@latest", () => {
+	// Contract amended at the merge with origin/main (see requirements R1.1): the
+	// released 7.3.1 API is selfUpgradeCommand → { cmd, args } with `install -g`.
+	test("R1.1 selfUpgradeCommand('bun') is `bun install -g magus-cli@latest`", async () => {
+		const { selfUpgradeCommand } = await loadUpgrade();
+		expect(selfUpgradeCommand("bun")).toEqual({
+			cmd: "bun",
+			args: ["install", "-g", "magus-cli@latest"],
+		});
+	});
+
+	test("R1.1 selfUpgradeCommand('npm') is `npm install -g magus-cli@latest`", async () => {
+		const { selfUpgradeCommand } = await loadUpgrade();
+		expect(selfUpgradeCommand("npm")).toEqual({
+			cmd: "npm",
+			args: ["install", "-g", "magus-cli@latest"],
+		});
+	});
+
+	test("R1.1 neither upgrade command names the bare `magus` package", async () => {
+		const { selfUpgradeCommand } = await loadUpgrade();
+		for (const pm of ["bun", "npm"] as const) {
+			const { args } = selfUpgradeCommand(pm);
+			const bare = args.filter((a: string) => BARE_MAGUS.test(a));
+			expect({ pm, bare }).toEqual({ pm, bare: [] });
+		}
+	});
+
+	test("R1.1/R1.5 the upgrade package spec is MAGUS_NPM_PACKAGE@latest", async () => {
+		const { selfUpgradeCommand } = await loadUpgrade();
+		const { MAGUS_NPM_PACKAGE } = await loadNpmPackage();
+		for (const pm of ["bun", "npm"] as const) {
+			expect(selfUpgradeCommand(pm).args).toContain(
+				`${MAGUS_NPM_PACKAGE}@latest`,
+			);
+		}
+	});
+});
+
+describe("C1 — the update check asks the magus-cli registry document", () => {
+	test(
+		"R1.3 checkForUpdates(true) requests https://registry.npmjs.org/magus-cli/latest",
+		() => {
+			const requested = forcedCheckUrls();
+			// The forced check must actually go to the network (through the mock).
+			expect(requested.length).toBeGreaterThanOrEqual(1);
+			// Every request it made is the magus-cli document — never /magus/latest.
+			expect(requested).toEqual(requested.map(() => REGISTRY_URL));
+		},
+		T,
+	);
+
+	test(
+		"R1.3 the update check never asks for the bare `magus` registry document",
+		() => {
+			const bare = forcedCheckUrls().filter((u) =>
+				/registry\.npmjs\.org\/magus(\/|$)/.test(u),
+			);
+			expect(bare).toEqual([]);
+		},
+		T,
+	);
+});
+
+describe("C1 — the CLI Tools entry for magus uses magus-cli", () => {
+	test("R1.4 the cliTools entry named magus exists", async () => {
+		const { cliTools } = await loadCliTools();
+		expect(
+			cliTools.find((t: { name: string }) => t.name === "magus"),
+		).toBeDefined();
+	});
+
+	test("R1.4 the magus CLI Tools entry has packageName magus-cli", async () => {
+		const { cliTools } = await loadCliTools();
+		const entry = cliTools.find((t: { name: string }) => t.name === "magus");
+		expect(entry?.packageName).toBe("magus-cli");
+	});
+
+	test("R1.4/R1.5 the magus CLI Tools entry's packageName is MAGUS_NPM_PACKAGE", async () => {
+		const { cliTools } = await loadCliTools();
+		const { MAGUS_NPM_PACKAGE } = await loadNpmPackage();
+		const entry = cliTools.find((t: { name: string }) => t.name === "magus");
+		expect(entry?.packageName).toBe(MAGUS_NPM_PACKAGE);
+	});
+
+	test("R1.4 any install/add command string on the magus entry installs magus-cli, never bare magus", async () => {
+		// The contract elides the entry's other fields (`/*…*/`). If one of them
+		// is a displayed command, it must name magus-cli. With no such field the
+		// check has nothing to inspect and passes; packageName is pinned above.
+		const { cliTools } = await loadCliTools();
+		const entry = cliTools.find((t: { name: string }) => t.name === "magus");
+		expect(entry).toBeDefined();
+		const offenders: string[] = [];
+		for (const [key, value] of Object.entries(entry ?? {})) {
+			if (typeof value !== "string") continue;
+			if (!/\b(install|add)\b/.test(value)) continue;
+			if (!value.includes("magus-cli") || BARE_MAGUS.test(value)) {
+				offenders.push(`${key}: ${value}`);
+			}
+		}
+		expect(offenders).toEqual([]);
+	});
+});

package/src/__tests__/blind/c10-colour-roles.test.ts

@@ -0,0 +1,265 @@
+/**
+ * Blind tests — contract C10 (requirements R10.2, R10.3).
+ *
+ * Written from requirements.md and architecture.md only. Two kinds of check:
+ *  - the exported `theme` object is walked key by key, at every depth;
+ *  - `src/ui/**` source text is scanned (theme.ts and theme-mode.ts excepted)
+ *    and every offending `file:line` is listed in the failure.
+ */
+import { describe, expect, test } from "bun:test";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+
+const loadTheme = () => import("../../ui/theme.js");
+
+const UI_DIR = path.resolve(import.meta.dir, "../../ui");
+/** Paths relative to src/ui that may hold colour literals. */
+const EXEMPT = new Set(["theme.ts", "theme-mode.ts"]);
+
+const COLOUR_WORDS = [
+	"purple",
+	"green",
+	"teal",
+	"yellow",
+	"gray",
+	"grey",
+	"red",
+	"blue",
+	"orange",
+	"cyan",
+	"magenta",
+	"pink",
+	"violet",
+	"amber",
+];
+const COLOUR_WORD_SET = new Set(COLOUR_WORDS);
+
+/** CSS named colours likely to be typed as a literal (R10.3 "named CSS colour string"). */
+const CSS_NAMED = new Set([
+	...COLOUR_WORDS.filter((w) => w !== "amber"),
+	"black",
+	"white",
+	"silver",
+	"maroon",
+	"olive",
+	"lime",
+	"aqua",
+	"navy",
+	"fuchsia",
+	"brown",
+	"gold",
+	"indigo",
+	"coral",
+	"salmon",
+	"crimson",
+	"lightgray",
+	"lightgrey",
+	"darkgray",
+	"darkgrey",
+]);
+
+/** Split an identifier into lowercase words: "textGray500" -> ["text","gray","500"]. */
+function words(name: string): string[] {
+	return name
+		.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+		.replace(/([A-Za-z])([0-9])/g, "$1 $2")
+		.split(/[^A-Za-z0-9]+/)
+		.filter(Boolean)
+		.map((w) => w.toLowerCase());
+}
+const colourWordIn = (name: string) =>
+	words(name).find((w) => COLOUR_WORD_SET.has(w));
+
+function walkFiles(dir: string): string[] {
+	const out: string[] = [];
+	for (const name of readdirSync(dir)) {
+		const full = path.join(dir, name);
+		if (statSync(full).isDirectory()) out.push(...walkFiles(full));
+		else if (/\.(ts|tsx)$/.test(name)) out.push(full);
+	}
+	return out;
+}
+
+function uiFiles(): string[] {
+	return walkFiles(UI_DIR).filter((f) => !EXEMPT.has(path.relative(UI_DIR, f)));
+}
+
+function isCommentLine(line: string): boolean {
+	const t = line.trim();
+	return (
+		t.startsWith("//") ||
+		t.startsWith("*") ||
+		t.startsWith("/*") ||
+		t.startsWith("{/*")
+	);
+}
+
+/** Every non-comment line of every scanned file matching `rule`, as `file:line: text`. */
+function scan(rule: (line: string) => boolean): string[] {
+	const hits: string[] = [];
+	for (const file of uiFiles()) {
+		readFileSync(file, "utf8")
+			.split("\n")
+			.forEach((line, i) => {
+				if (isCommentLine(line)) return;
+				if (rule(line)) {
+					hits.push(
+						`src/ui/${path.relative(UI_DIR, file)}:${i + 1}: ${line.trim().slice(0, 140)}`,
+					);
+				}
+			});
+	}
+	return hits;
+}
+
+const COLOUR_PROPS = "fg|bg|backgroundColor|borderColor|color";
+const HEX_LITERAL =
+	/(["'`])#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3})\1/;
+const RGB_IN_STRING = /["'`][^"'`\n]*\brgba?\s*\(/;
+/** fg="…", fg='…', fg={"…"}, fg={`…`} */
+const JSX_PROP_LITERAL = new RegExp(
+	`(?<![\\w$.])(?:${COLOUR_PROPS})\\s*=\\s*(?:\\{\\s*)?["'\`]`,
+);
+/** fg={cond ? "…" : x} — a string literal inside the prop's expression. */
+const JSX_PROP_TERNARY_LITERAL = new RegExp(
+	`(?<![\\w$.])(?:${COLOUR_PROPS})\\s*=\\s*\\{[^}]*[?:]\\s*["'\`]`,
+);
+/** { fg: "red" } — an object colour prop set to a named CSS colour. */
+const OBJECT_PROP_NAMED = new RegExp(
+	`(?<![\\w$.])(?:${COLOUR_PROPS})\\s*:\\s*["'\`]([A-Za-z]+)["'\`]`,
+);
+
+describe("C10 — scan setup", () => {
+	test("R10.3 control: the scan finds UI source files and exempts only theme.ts and theme-mode.ts", () => {
+		const all = walkFiles(UI_DIR).map((f) => path.relative(UI_DIR, f));
+		expect(all.length).toBeGreaterThan(10);
+		expect(all).toContain("theme.ts");
+		expect(uiFiles().length).toBe(
+			all.length - all.filter((f) => EXEMPT.has(f)).length,
+		);
+	});
+
+	test("R10.3 control: the rules fire on known-bad lines and stay quiet on role references", () => {
+		expect(HEX_LITERAL.test('const c = "#ff00aa";')).toBe(true);
+		expect(HEX_LITERAL.test("fg='#abc'")).toBe(true);
+		expect(HEX_LITERAL.test('x = "#aabbccdd"')).toBe(true);
+		expect(RGB_IN_STRING.test('bg: "rgb(1, 2, 3)"')).toBe(true);
+		expect(RGB_IN_STRING.test('bg: "rgba(1,2,3,0.5)"')).toBe(true);
+		expect(JSX_PROP_LITERAL.test('<text fg="gray">')).toBe(true);
+		expect(JSX_PROP_LITERAL.test("<box backgroundColor={'#000'}>")).toBe(true);
+		expect(
+			JSX_PROP_TERNARY_LITERAL.test(
+				'<text fg={on ? "green" : theme.colors.muted}>',
+			),
+		).toBe(true);
+		expect(OBJECT_PROP_NAMED.test('style={{ fg: "red" }}')).toBe(true);
+		const clean = "<text fg={theme.colors.accent} bg={theme.colors.surface}>";
+		expect(HEX_LITERAL.test(clean)).toBe(false);
+		expect(RGB_IN_STRING.test(clean)).toBe(false);
+		expect(JSX_PROP_LITERAL.test(clean)).toBe(false);
+		expect(JSX_PROP_TERNARY_LITERAL.test(clean)).toBe(false);
+		expect(OBJECT_PROP_NAMED.test(clean)).toBe(false);
+	});
+});
+
+describe("C10 — no colour literal in src/ui outside the theme files (R10.3)", () => {
+	test('R10.3 no hex colour string literal ("#abc", "#aabbcc", "#aabbccdd")', () => {
+		expect(scan((l) => HEX_LITERAL.test(l))).toEqual([]);
+	});
+
+	test("R10.3 no rgb( / rgba( inside a string", () => {
+		expect(scan((l) => RGB_IN_STRING.test(l))).toEqual([]);
+	});
+
+	test("R10.3 no JSX colour prop (fg, bg, backgroundColor, borderColor, color) set to a string literal", () => {
+		expect(
+			scan((l) => JSX_PROP_LITERAL.test(l) || JSX_PROP_TERNARY_LITERAL.test(l)),
+		).toEqual([]);
+	});
+
+	test("R10.3 no colour prop in an object set to a named CSS colour string", () => {
+		expect(
+			scan((l) => {
+				const m = OBJECT_PROP_NAMED.exec(l);
+				return !!m && CSS_NAMED.has((m[1] as string).toLowerCase());
+			}),
+		).toEqual([]);
+	});
+});
+
+describe("C10 — every colour is a role, never a colour name (R10.2)", () => {
+	test("R10.2 control: the colour-word splitter catches camelCase, snake_case and digits, not substrings", () => {
+		expect(colourWordIn("purple")).toBe("purple");
+		expect(colourWordIn("textGray")).toBe("gray");
+		expect(colourWordIn("gray500")).toBe("gray");
+		expect(colourWordIn("bg_red")).toBe("red");
+		expect(colourWordIn("redraw")).toBeUndefined();
+		expect(colourWordIn("reduced")).toBeUndefined();
+		expect(colourWordIn("accent")).toBeUndefined();
+	});
+
+	test("R10.2 no key of the exported theme, at any depth, is named after a colour", async () => {
+		const { theme } = await loadTheme();
+		expect(theme).toBeDefined();
+		const offenders: string[] = [];
+		const seen = new Set<unknown>();
+		const visit = (value: unknown, at: string) => {
+			if (value === null || typeof value !== "object" || seen.has(value))
+				return;
+			seen.add(value);
+			const proto = Object.getPrototypeOf(value);
+			const plain =
+				proto === Object.prototype || proto === null || Array.isArray(value);
+			if (!plain) return; // a colour value object (e.g. an RGBA instance), not a namespace
+			for (const key of Object.keys(value)) {
+				const word = colourWordIn(key);
+				if (word) offenders.push(`theme${at}.${key} (${word})`);
+				visit((value as Record<string, unknown>)[key], `${at}.${key}`);
+			}
+		};
+		visit(theme, "");
+		expect(offenders).toEqual([]);
+	});
+
+	test("R10.2 the theme walk visits some keys (control)", async () => {
+		const { theme } = await loadTheme();
+		const count = (v: unknown): number =>
+			v && typeof v === "object"
+				? Object.keys(v).reduce(
+						(n, k) => n + 1 + count((v as Record<string, unknown>)[k]),
+						0,
+					)
+				: 0;
+		expect(count(theme)).toBeGreaterThan(3);
+	});
+
+	test("R10.2 no prop or variable in src/ui is named after a colour", () => {
+		// Strings and trailing comments are blanked first so text such as
+		// "Green means installed" is not read as a name. Checked: declarations,
+		// property accesses, object keys and JSX props.
+		const NAME = "[A-Za-z_$][\\w$]*";
+		const patterns = [
+			new RegExp(
+				`\\b(?:const|let|var|function|class|type|interface)\\s+(${NAME})`,
+				"g",
+			),
+			new RegExp(`\\.(${NAME})`, "g"),
+			new RegExp(`(?:^|[\\s{(,])(${NAME})\\??\\s*:(?!:)`, "g"),
+			new RegExp(`(?:^|\\s)(${NAME})\\s*=(?![=>])`, "g"),
+			new RegExp(`\\{\\s*(${NAME})\\s*[,}]`, "g"),
+		];
+		const hits = scan((raw) => {
+			const code = raw
+				.replace(/(["'`])(?:\\.|(?!\1).)*\1/g, '""')
+				.replace(/\/\/.*$/, "")
+				.replace(/\/\*.*?\*\//g, "");
+			for (const p of patterns) {
+				for (const m of code.matchAll(p)) {
+					if (colourWordIn(m[1] as string)) return true;
+				}
+			}
+			return false;
+		});
+		expect(hits).toEqual([]);
+	});
+});