magus-cli 7.11.7 → 7.12.0

package/src/__tests__/alias-env-adoption.test.ts

@@ -0,0 +1,334 @@
+import { describe, expect, it } from "bun:test";
+import {
+	argsToFlagValuesWithLeftovers,
+	findAdoptableAlias,
+	parseAliasFromRc,
+	parseAliasLine,
+	parseManagedBlock,
+	renderAlias,
+} from "../services/alias-shell-writer";
+import type { AliasConfig, FlagValue } from "../services/alias-store";
+
+const assignment = "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1";
+
+function combinedFlags(): Record<string, FlagValue> {
+	return {
+		"agent-teams": { kind: "boolean", enabled: true },
+		"teammate-mode": { kind: "select", enabled: true, value: "tmux" },
+		autocompact: { kind: "text", enabled: true, value: "200k" },
+	};
+}
+
+const forms: Array<{
+	name: string;
+	envLauncher: boolean;
+	line: (body: string) => string;
+}> = [
+	{ name: "POSIX", envLauncher: false, line: (body) => `alias crew='${body}'` },
+	// The env launcher is a body form; the parser contract uses POSIX alias lines.
+	{
+		name: "POSIX with env launcher",
+		envLauncher: true,
+		line: (body) => `alias crew='${body}'`,
+	},
+];
+
+function commandBody(
+	envLauncher: boolean,
+	env: string[],
+	argv: string[],
+): string {
+	return [
+		...(envLauncher && env.length > 0 ? ["env"] : []),
+		...env,
+		"claude",
+		...argv,
+	].join(" ");
+}
+
+describe("managed assignment-prefixed alias parsing", () => {
+	const examples = [
+		{
+			name: "POSIX known assignment",
+			line: `alias crew='${assignment} claude --teammate-mode tmux --autocompact 200k'`,
+			args: [assignment, "--teammate-mode", "tmux", "--autocompact", "200k"],
+		},
+		{
+			name: "POSIX alias with env launcher",
+			line: `alias crew='env ${assignment} claude --teammate-mode tmux --autocompact 200k'`,
+			args: [assignment, "--teammate-mode", "tmux", "--autocompact", "200k"],
+		},
+		{
+			name: "POSIX unknown before known assignment",
+			line: `alias crew='EXTRA=keep ${assignment} claude --autocompact 200k'`,
+			args: ["EXTRA=keep", assignment, "--autocompact", "200k"],
+		},
+		{
+			name: "POSIX env launcher with unknown after known assignment",
+			line: `alias crew='env ${assignment} EXTRA=a=b claude --teammate-mode tmux'`,
+			args: [assignment, "EXTRA=a=b", "--teammate-mode", "tmux"],
+		},
+	];
+
+	for (const example of examples) {
+		it(`TEST-15 REQ-11 preserves env-first tokens for ${example.name}`, () => {
+			const block = [
+				"# >>> magus managed alias >>>",
+				example.line,
+				"# <<< magus managed alias <<<",
+				"",
+			].join("\n");
+			const expected = { aliasName: "crew", args: [...example.args] };
+
+			expect(parseAliasLine(example.line)).toEqual(expected);
+			expect(parseManagedBlock(block)).toEqual(expected);
+		});
+	}
+});
+
+describe("assignment mapping and leftovers", () => {
+	const mappingCases: Array<{
+		name: string;
+		args: string[];
+		flags: () => Record<string, FlagValue>;
+		leftovers: string[];
+	}> = [
+		{
+			name: "known assignment and all new argv options",
+			args: [assignment, "--teammate-mode", "tmux", "--autocompact", "200k"],
+			flags: combinedFlags,
+			leftovers: [],
+		},
+		{
+			name: "unknown assignment before the known one",
+			args: [
+				"EXTRA=keep",
+				assignment,
+				"--teammate-mode",
+				"tmux",
+				"--autocompact",
+				"200k",
+			],
+			flags: combinedFlags,
+			leftovers: ["EXTRA=keep"],
+		},
+		{
+			name: "unknown assignments after the known one",
+			args: [
+				assignment,
+				"EMPTY=",
+				"EXTRA=a=b",
+				"--teammate-mode",
+				"tmux",
+				"--autocompact",
+				"200k",
+			],
+			flags: combinedFlags,
+			leftovers: ["EMPTY=", "EXTRA=a=b"],
+		},
+		{
+			name: "known env name with a different value",
+			args: ["CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=0", "--ide"],
+			flags: () => ({ ide: { kind: "boolean", enabled: true } }),
+			leftovers: ["CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=0"],
+		},
+	];
+
+	for (const example of mappingCases) {
+		it(`TEST-16 REQ-12 retains every unmatched token for ${example.name}`, () => {
+			const args = [...example.args];
+
+			expect(argsToFlagValuesWithLeftovers(args)).toEqual({
+				flags: example.flags(),
+				leftovers: [...example.leftovers],
+			});
+		});
+	}
+
+	it("TEST-17 REQ-12 keeps an assignment after an argv flag as a leftover rather than enabling teams", () => {
+		const args = ["--ide", assignment];
+
+		expect(argsToFlagValuesWithLeftovers(args)).toEqual({
+			flags: { ide: { kind: "boolean", enabled: true } },
+			leftovers: [assignment],
+		});
+	});
+
+	it("TEST-17 REQ-12 retains an argv assignment without losing an earlier recognized env assignment", () => {
+		const args = [assignment, "--ide", "EXTRA=keep"];
+
+		expect(argsToFlagValuesWithLeftovers(args)).toEqual({
+			flags: {
+				"agent-teams": { kind: "boolean", enabled: true },
+				ide: { kind: "boolean", enabled: true },
+			},
+			leftovers: ["EXTRA=keep"],
+		});
+	});
+
+	it("TEST-17 REQ-12 leaves an assignment used as a text value inside that text flag", () => {
+		const args = ["--append-system-prompt", assignment];
+
+		expect(argsToFlagValuesWithLeftovers(args)).toEqual({
+			flags: {
+				"append-system-prompt": {
+					kind: "text",
+					enabled: true,
+					value: assignment,
+				},
+			},
+			leftovers: [],
+		});
+	});
+});
+
+describe("safe adoption of assignment-prefixed aliases", () => {
+	const losslessCases: Array<{
+		name: string;
+		env: string[];
+		argv: string[];
+		flags: () => Record<string, FlagValue>;
+	}> = [
+		{
+			name: "context size only",
+			env: [],
+			argv: ["--autocompact", "200k"],
+			flags: () => ({
+				autocompact: { kind: "text", enabled: true, value: "200k" },
+			}),
+		},
+		{
+			name: "agent teams only",
+			env: [assignment],
+			argv: [],
+			flags: () => ({
+				"agent-teams": { kind: "boolean", enabled: true },
+			}),
+		},
+		{
+			name: "all new options",
+			env: [assignment],
+			argv: ["--teammate-mode", "tmux", "--autocompact", "200k"],
+			flags: combinedFlags,
+		},
+	];
+
+	const unknownCases: Array<{
+		name: string;
+		env: string[];
+		argv: string[];
+		flags: () => Record<string, FlagValue>;
+		leftovers: string[];
+	}> = [
+		{
+			name: "an unknown assignment alone",
+			env: ["EXTRA=keep"],
+			argv: ["--ide"],
+			flags: () => ({ ide: { kind: "boolean", enabled: true } }),
+			leftovers: ["EXTRA=keep"],
+		},
+		{
+			name: "an empty-valued unknown assignment before known teams",
+			env: ["EMPTY=", assignment],
+			argv: ["--teammate-mode", "tmux", "--autocompact", "200k"],
+			flags: combinedFlags,
+			leftovers: ["EMPTY="],
+		},
+		{
+			name: "an unknown assignment containing another equals sign after known teams",
+			env: [assignment, "EXTRA=a=b"],
+			argv: ["--teammate-mode", "tmux", "--autocompact", "200k"],
+			flags: combinedFlags,
+			leftovers: ["EXTRA=a=b"],
+		},
+		{
+			name: "a known assignment name with an unsupported value",
+			env: ["CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=0"],
+			argv: ["--ide"],
+			flags: () => ({ ide: { kind: "boolean", enabled: true } }),
+			leftovers: ["CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=0"],
+		},
+	];
+
+	for (const form of forms) {
+		for (const example of losslessCases) {
+			it(`TEST-18 REQ-11 REQ-13 adopts ${example.name} losslessly in ${form.name}`, () => {
+				const line = form.line(
+					commandBody(form.envLauncher, example.env, example.argv),
+				);
+				const rc = `# personal aliases\n${line}\n# end aliases\n`;
+				const expectedFlags = example.flags();
+
+				const adopted = findAdoptableAlias(rc);
+
+				expect(adopted).toEqual({
+					name: "crew",
+					flags: expectedFlags,
+					lineRange: [1, 1],
+					leftovers: [],
+					lossless: true,
+					rawLine: line,
+					others: [],
+				});
+				if (adopted === null) {
+					throw new Error("Expected a lossless adoptable alias");
+				}
+				const config: AliasConfig = {
+					aliasName: adopted.name,
+					flags: adopted.flags,
+				};
+				expect(parseAliasFromRc(renderAlias(config, "bash").block)).toEqual({
+					aliasName: "crew",
+					flags: expectedFlags,
+				});
+			});
+		}
+
+		for (const example of unknownCases) {
+			it(`TEST-19 REQ-11 REQ-12 REQ-13 preserves ${example.name} as a leftover in ${form.name}`, () => {
+				const line = form.line(
+					commandBody(form.envLauncher, example.env, example.argv),
+				);
+				const rc = `# personal aliases\n${line}\n# end aliases\n`;
+
+				const adopted = findAdoptableAlias(rc);
+
+				expect(adopted).toEqual({
+					name: "crew",
+					flags: example.flags(),
+					lineRange: [1, 1],
+					leftovers: [...example.leftovers],
+					lossless: false,
+					rawLine: line,
+					others: [],
+				});
+			});
+		}
+
+		it(`TEST-20 REQ-13 REQ-14 refuses lossless adoption of orphan teammate-mode in ${form.name}`, () => {
+			const line = form.line("claude --teammate-mode tmux");
+
+			const adopted = findAdoptableAlias(`${line}\n`);
+
+			expect(adopted).toEqual({
+				name: "crew",
+				flags: {
+					"teammate-mode": { kind: "select", enabled: true, value: "tmux" },
+				},
+				lineRange: [0, 0],
+				leftovers: [],
+				lossless: false,
+				rawLine: line,
+				others: [],
+			});
+		});
+
+		it(`TEST-21 REQ-11 rejects an assignment-prefixed non-claude alias in ${form.name}`, () => {
+			const prefix = form.envLauncher ? "env " : "";
+			const line = form.line(`${prefix + assignment} other-command --ide`);
+
+			expect(parseAliasLine(line)).toBeNull();
+			expect(findAdoptableAlias(`${line}\n`)).toBeNull();
+		});
+	}
+});

package/src/__tests__/alias-option-compatibility.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "bun:test";
+import {
+	type ShellKind,
+	renderAlias,
+	renderArgsAsTokens,
+	renderEnv,
+} from "../services/alias-shell-writer";
+import {
+	type AliasConfig,
+	type FlagValue,
+	defaultAliasConfig,
+} from "../services/alias-store";
+
+const shells: ShellKind[] = ["bash", "zsh", "fish"];
+
+describe("alias output when the new options are not enabled", () => {
+	const establishedCases: Array<{
+		name: string;
+		flags: () => Record<string, FlagValue>;
+		tokens: string[];
+		posixLine: string;
+		fishLine: string;
+	}> = [
+		{
+			name: "plain claude alias",
+			flags: () => ({}),
+			tokens: [],
+			posixLine: "alias c='claude'",
+			fishLine: "alias c 'claude'",
+		},
+		{
+			name: "ide-only alias",
+			flags: () => ({ ide: { kind: "boolean", enabled: true } }),
+			tokens: ["--ide"],
+			posixLine: "alias c='claude --ide'",
+			fishLine: "alias c 'claude '--ide''",
+		},
+	];
+
+	for (const shell of shells) {
+		for (const example of establishedCases) {
+			it(`TEST-22 REQ-10 preserves established ${example.name} bytes on ${shell} with absent or disabled new options`, () => {
+				const absent: AliasConfig = {
+					aliasName: "c",
+					flags: example.flags(),
+				};
+				const disabled: AliasConfig = {
+					aliasName: "c",
+					flags: {
+						...example.flags(),
+						autocompact: { kind: "text", enabled: false, value: "200k" },
+						"agent-teams": { kind: "boolean", enabled: false },
+						"teammate-mode": { kind: "select", enabled: false, value: "tmux" },
+					},
+				};
+
+				const absentOutput = renderAlias(absent, shell);
+				const disabledOutput = renderAlias(disabled, shell);
+
+				expect(absentOutput.shell).toBe(shell);
+				expect(disabledOutput).toEqual(absentOutput);
+				expect(
+					absentOutput.block
+						.split("\n")
+						.filter((line) => line.startsWith("alias ")),
+				).toEqual([shell === "fish" ? example.fishLine : example.posixLine]);
+				expect(
+					absentOutput.block.startsWith("# >>> magus managed alias >>>\n"),
+				).toBe(true);
+				expect(
+					absentOutput.block.endsWith("# <<< magus managed alias <<<\n"),
+				).toBe(true);
+				expect(renderEnv(absent)).toEqual([]);
+				expect(renderEnv(disabled)).toEqual([]);
+				expect(renderArgsAsTokens(absent)).toEqual([...example.tokens]);
+				expect(renderArgsAsTokens(disabled)).toEqual([...example.tokens]);
+			});
+		}
+
+		it(`TEST-23 REQ-10 leaves all new options off in the default ${shell} alias`, () => {
+			const config = defaultAliasConfig();
+			const emptyConfig: AliasConfig = { aliasName: "c", flags: {} };
+
+			expect(config.aliasName).toBe("c");
+			expect(renderEnv(config)).toEqual([]);
+			expect(renderArgsAsTokens(config)).toEqual([]);
+			expect(renderAlias(config, shell)).toEqual(
+				renderAlias(emptyConfig, shell),
+			);
+		});
+	}
+});

package/src/__tests__/marketplace-refresh.test.ts

@@ -15,18 +15,36 @@ import path from "node:path";
 // --- Mock the marketplace registry (the only magus dep of the refresher) ---
 let configured: Record<string, { source: { source: string; repo?: string } }>;
 let autoUpdate: Record<string, boolean | undefined>;
+/**
+ * USER-scope `enabledPlugins`. `null` means "one USER plugin from every
+ * registered marketplace", so the cases written before the needed-only rule
+ * keep exercising the pull itself; the needed-only cases set it explicitly.
+ */
+let userEnabled: Record<string, boolean> | null;
 
 mock.module("../services/claude-settings.js", () => ({
 	getConfiguredMarketplaces: async () => configured,
 	getMarketplaceAutoUpdate: async (name: string) => autoUpdate[name],
+	getGlobalEnabledPlugins: async () =>
+		userEnabled ??
+		Object.fromEntries(Object.keys(configured).map((n) => [`p@${n}`, true])),
 	// The refresher resolves clone paths via this helper; point it at our temp
 	// home so no real ~/.claude marketplace is ever touched. (Bun's os.homedir()
 	// ignores runtime $HOME changes, so mocking the helper is the reliable seam.)
 	getGlobalClaudeDir: () => path.join(tmp, ".claude"),
 }));
 
-const { refreshRegisteredMarketplaces, fastForwardCloneIfPresent } =
-	await import("../services/marketplace-refresh.js");
+const {
+	refreshRegisteredMarketplaces,
+	reportRegisteredMarketplaces,
+	fastForwardCloneIfPresent,
+} = await import("../services/marketplace-refresh.js");
+const {
+	CATALOG_TTL_MS,
+	clearCloneRefreshes,
+	readCloneRefreshAge,
+	resetCatalogCacheMemo,
+} = await import("../services/catalog-cache-store.js");
 
 const gh = (repo = "MadAppGang/magus") => ({
 	source: { source: "github", repo },
@@ -110,6 +128,7 @@ beforeEach(() => {
 
 	configured = {};
 	autoUpdate = {};
+	userEnabled = null;
 });
 
 afterEach(() => {
@@ -457,3 +476,193 @@ describe("fastForwardCloneIfPresent — per-clone deadline", () => {
 		expect(await goneWithin(readPid(pullPid), 1_000)).toBe(true);
 	}, 10_000);
 });
+
+/** The clone's HEAD and origin's main, to tell "pulled" from "left behind". */
+function headOf(dir: string): string {
+	return git(dir, "rev-parse", "HEAD").trim();
+}
+function originHead(): string {
+	return git(origin, "rev-parse", "main").trim();
+}
+
+describe("refreshRegisteredMarketplaces — needed only (MTL-367)", () => {
+	it("does not pull a registered marketplace no installed plugin comes from, and reports it skipped", async () => {
+		const used = installClone("magus");
+		const unused = installClone("unused");
+		publishV2();
+		configured = { magus: gh(), unused: gh("x/unused") };
+		userEnabled = {};
+
+		const r = await refreshRegisteredMarketplaces(
+			[],
+			{},
+			{ pluginIds: ["dev@magus"] },
+		);
+
+		expect(r.refreshed).toEqual(["magus"]);
+		expect(r.skipped).toEqual(["unused"]);
+		expect(headOf(used)).toBe(originHead());
+		expect(headOf(unused)).not.toBe(originHead()); // left behind
+	});
+
+	it("pulls a marketplace used only by a USER-scope plugin", async () => {
+		const dir = installClone("userland");
+		installClone("unused");
+		publishV2();
+		configured = { userland: gh("x/userland"), unused: gh("x/unused") };
+		// `false` is not installed: only `true` counts.
+		userEnabled = { "tool@userland": true, "off@unused": false };
+
+		const r = await refreshRegisteredMarketplaces([], {}, { pluginIds: [] });
+
+		expect(r.refreshed).toEqual(["userland"]);
+		expect(r.skipped).toEqual(["unused"]);
+		expect(headOf(dir)).toBe(originHead());
+	});
+
+	it("report-only applies the same selection: an unused marketplace is skipped, a used one pending", async () => {
+		installClone("magus");
+		installClone("unused");
+		configured = { magus: gh(), unused: gh("x/unused") };
+		userEnabled = {};
+
+		const r = await reportRegisteredMarketplaces([], {
+			pluginIds: ["dev@magus"],
+		});
+
+		expect(r.refreshed).toEqual([]);
+		expect(r.pending).toEqual(["magus"]);
+		expect(r.skipped).toEqual(["unused"]);
+	});
+});
+
+describe("refreshRegisteredMarketplaces — at most once an hour, machine-wide (MTL-367)", () => {
+	let prevConfigDir: string | undefined;
+	const T0 = 1_790_000_000_000;
+
+	beforeEach(() => {
+		prevConfigDir = process.env.CLAUDE_CONFIG_DIR;
+		// The store lives under the temp home, never the operator's.
+		process.env.CLAUDE_CONFIG_DIR = path.join(tmp, ".claude");
+		resetCatalogCacheMemo();
+	});
+	afterEach(() => {
+		// biome-ignore lint/performance/noDelete: assigning undefined stores the string "undefined"
+		if (prevConfigDir === undefined) delete process.env.CLAUDE_CONFIG_DIR;
+		else process.env.CLAUDE_CONFIG_DIR = prevConfigDir;
+		resetCatalogCacheMemo();
+	});
+
+	it("does not pull again within the hour, and reports it fresh", async () => {
+		const dir = installClone("magus");
+		configured = { magus: gh() };
+
+		const first = await refreshRegisteredMarketplaces([], {}, { now: T0 });
+		expect(first.refreshed).toEqual(["magus"]);
+
+		publishV2(); // origin advances after the first pull
+		resetCatalogCacheMemo(); // a second process, same machine
+		const before = headOf(dir);
+		const second = await refreshRegisteredMarketplaces(
+			[],
+			{},
+			{ now: T0 + 10 * 60 * 1000 },
+		);
+
+		expect(second.refreshed).toEqual([]);
+		expect(second.fresh).toEqual(["magus"]);
+		expect(second.skipped).toEqual([]);
+		expect(headOf(dir)).toBe(before);
+		expect(headOf(dir)).not.toBe(originHead());
+	});
+
+	it("pulls again once the TTL has passed", async () => {
+		const dir = installClone("magus");
+		configured = { magus: gh() };
+		await refreshRegisteredMarketplaces([], {}, { now: T0 });
+
+		publishV2();
+		const r = await refreshRegisteredMarketplaces(
+			[],
+			{},
+			{ now: T0 + CATALOG_TTL_MS + 1 },
+		);
+
+		expect(r.refreshed).toEqual(["magus"]);
+		expect(r.fresh).toEqual([]);
+		expect(headOf(dir)).toBe(originHead());
+	});
+
+	it("a failed pull records no time, so the next call pulls again", async () => {
+		const dir = installClone("magus");
+		git(dir, "remote", "set-url", "origin", path.join(tmp, "gone.git"));
+		configured = { magus: gh() };
+
+		const failed = await refreshRegisteredMarketplaces([], {}, { now: T0 });
+		expect(failed.failed).toEqual(["magus"]);
+		expect(await readCloneRefreshAge("magus", T0 + 1)).toBeNull();
+
+		git(dir, "remote", "set-url", "origin", origin);
+		publishV2();
+		const retry = await refreshRegisteredMarketplaces(
+			[],
+			{},
+			{ now: T0 + 60_000 },
+		);
+		expect(retry.refreshed).toEqual(["magus"]);
+		expect(headOf(dir)).toBe(originHead());
+	});
+
+	it("an explicit refresh (the TUI's `r`) clears the record, so the next call pulls", async () => {
+		const dir = installClone("magus");
+		configured = { magus: gh() };
+		await refreshRegisteredMarketplaces([], {}, { now: T0 });
+
+		// `r` -> refreshAllMarketplaces -> clearPersistedCatalogs.
+		const { clearPersistedCatalogs } = await import(
+			"../services/marketplace-fetcher.js"
+		);
+		await clearPersistedCatalogs();
+
+		publishV2();
+		resetCatalogCacheMemo();
+		const r = await refreshRegisteredMarketplaces([], {}, { now: T0 + 60_000 });
+		expect(r.refreshed).toEqual(["magus"]);
+		expect(headOf(dir)).toBe(originHead());
+	});
+
+	it("clearCloneRefreshes drops the record", async () => {
+		installClone("magus");
+		configured = { magus: gh() };
+		await refreshRegisteredMarketplaces([], {}, { now: T0 });
+		expect(await readCloneRefreshAge("magus", T0 + 1)).toBe(1);
+
+		await clearCloneRefreshes();
+		expect(await readCloneRefreshAge("magus", T0 + 1)).toBeNull();
+	});
+
+	it("report-only writes no time, and the next writing run pulls", async () => {
+		const dir = installClone("magus");
+		configured = { magus: gh() };
+		publishV2();
+
+		const report = await reportRegisteredMarketplaces([], { now: T0 });
+		expect(report.pending).toEqual(["magus"]);
+		resetCatalogCacheMemo();
+		expect(await readCloneRefreshAge("magus", T0 + 1)).toBeNull();
+		expect(headOf(dir)).not.toBe(originHead());
+
+		const r = await refreshRegisteredMarketplaces([], {}, { now: T0 + 1 });
+		expect(r.refreshed).toEqual(["magus"]);
+	});
+
+	it("report-only reports a clone refreshed within the hour as fresh", async () => {
+		installClone("magus");
+		configured = { magus: gh() };
+		await refreshRegisteredMarketplaces([], {}, { now: T0 });
+
+		const report = await reportRegisteredMarketplaces([], { now: T0 + 1000 });
+		expect(report.fresh).toEqual(["magus"]);
+		expect(report.pending).toEqual([]);
+	});
+});