claudeup 4.19.0 → 4.23.0

package/src/__tests__/profile-sync.test.ts

@@ -0,0 +1,136 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import fs from "fs-extra";
+import { computeSync, syncProfile } from "../services/profile-sync.js";
+import { profileDir } from "../services/symlink-manager.js";
+import type { ProfileManifestEntry } from "../types/index.js";
+
+describe("computeSync (pure)", () => {
+	const entry: ProfileManifestEntry = {
+		name: "Frontend",
+		plugins: { "dev@magus": "2.9.0", "terminal@magus": "latest" },
+		settings: { effortLevel: "high" },
+	};
+
+	test("adds a newly-enabled plugin, preserving existing pins", () => {
+		const { entry: next, changes } = computeSync(
+			entry,
+			{
+				enabledPlugins: {
+					"dev@magus": true,
+					"terminal@magus": true,
+					"designer@magus": true,
+				},
+				effortLevel: "high",
+			},
+			{ mcpServers: {} },
+		);
+		// existing pin preserved (not downgraded to latest)
+		expect(next.plugins!["dev@magus"]).toBe("2.9.0");
+		// new plugin added as latest
+		expect(next.plugins!["designer@magus"]).toBe("latest");
+		expect(changes).toContainEqual({ kind: "plugin-added", detail: "designer@magus" });
+	});
+
+	test("removes a plugin that was disabled", () => {
+		const { entry: next, changes } = computeSync(
+			entry,
+			{ enabledPlugins: { "dev@magus": true }, effortLevel: "high" },
+			{ mcpServers: {} },
+		);
+		expect(next.plugins!["terminal@magus"]).toBeUndefined();
+		expect(changes).toContainEqual({ kind: "plugin-removed", detail: "terminal@magus" });
+	});
+
+	test("captures a settings change and an mcp change", () => {
+		const { entry: next, changes } = computeSync(
+			entry,
+			{
+				enabledPlugins: { "dev@magus": true, "terminal@magus": true },
+				effortLevel: "max",
+			},
+			{ mcpServers: { "chrome-devtools": { command: "npx" } } },
+		);
+		expect(next.settings!.effortLevel).toBe("max");
+		expect(next.mcpServers!["chrome-devtools"]).toEqual({ command: "npx" });
+		expect(changes.some((c) => c.kind === "settings-changed")).toBe(true);
+		expect(changes.some((c) => c.kind === "mcp-changed")).toBe(true);
+	});
+
+	test("no changes when the materialized state matches the manifest", () => {
+		const { changes } = computeSync(
+			entry,
+			{
+				enabledPlugins: { "dev@magus": true, "terminal@magus": true },
+				effortLevel: "high",
+			},
+			{ mcpServers: {} },
+		);
+		expect(changes).toEqual([]);
+	});
+
+	test("refreshes updatedAt to the injected timestamp when changed", () => {
+		const withStamp: ProfileManifestEntry = { ...entry, updatedAt: "OLD" };
+		const { entry: changed } = computeSync(
+			withStamp,
+			{ enabledPlugins: { "dev@magus": true, "terminal@magus": true, "new@magus": true }, effortLevel: "high" },
+			{ mcpServers: {} },
+			"2026-07-27T00:00:00.000Z",
+		);
+		expect(changed.updatedAt).toBe("2026-07-27T00:00:00.000Z");
+
+		// Unchanged sync leaves updatedAt alone.
+		const { entry: same } = computeSync(
+			withStamp,
+			{ enabledPlugins: { "dev@magus": true, "terminal@magus": true }, effortLevel: "high" },
+			{ mcpServers: {} },
+			"2026-07-27T00:00:00.000Z",
+		);
+		expect(same.updatedAt).toBe("OLD");
+	});
+});
+
+describe("syncProfile (io)", () => {
+	let dir: string;
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), "sync-"));
+		await fs.ensureDir(join(dir, ".claude"));
+		await fs.writeJson(join(dir, ".claude", "profiles.json"), {
+			version: 2,
+			profiles: { frontend: { name: "Frontend", plugins: { "dev@magus": "2.9.0" } } },
+		});
+	});
+	afterEach(async () => {
+		await rm(dir, { recursive: true, force: true });
+	});
+
+	test("promotes an edit in the materialized dir into the manifest file", async () => {
+		// A teammate enabled a new plugin directly in the active profile's settings.
+		const pd = profileDir("frontend", dir);
+		await fs.ensureDir(pd);
+		await fs.writeJson(join(pd, "settings.json"), {
+			enabledPlugins: { "dev@magus": true, "designer@magus": true },
+		});
+		await fs.writeJson(join(pd, "mcp.json"), { mcpServers: {} });
+
+		const { changes, wrote } = await syncProfile("frontend", dir);
+		expect(wrote).toBe(true);
+		expect(changes.some((c) => c.detail === "designer@magus")).toBe(true);
+
+		const manifest = await fs.readJson(join(dir, ".claude", "profiles.json"));
+		expect(manifest.profiles.frontend.plugins["designer@magus"]).toBe("latest");
+		expect(manifest.profiles.frontend.plugins["dev@magus"]).toBe("2.9.0"); // pin kept
+	});
+
+	test("no-op when nothing drifted", async () => {
+		const pd = profileDir("frontend", dir);
+		await fs.ensureDir(pd);
+		await fs.writeJson(join(pd, "settings.json"), {
+			enabledPlugins: { "dev@magus": true },
+		});
+		const { wrote } = await syncProfile("frontend", dir);
+		expect(wrote).toBe(false);
+	});
+});

package/src/__tests__/registry-version-resolution.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from "bun:test";
+import { pickRegistryEntry } from "../services/claude-settings.js";
+import type { InstalledPluginEntry } from "../types/index.js";
+
+/**
+ * Regression cover for the "no outdated plugins shown" bug.
+ *
+ * claudeup used to read installed versions from `settings.installedPluginVersions`
+ * only. Claude Code's own `plugin install` writes installed_plugins.json but not
+ * that settings key, so a genuinely installed plugin could be missing from it.
+ * The update check is `installedVersion && compare(latest, installedVersion) > 0`,
+ * so a missing version resolved to `hasUpdate: false` — an available update was
+ * reported as "up to date" rather than "unknown".
+ */
+
+const entry = (
+  scope: InstalledPluginEntry["scope"],
+  version: string,
+  projectPath?: string,
+): InstalledPluginEntry => ({
+  scope,
+  version,
+  projectPath,
+  installPath: `/cache/${version}`,
+  installedAt: "2026-01-01T00:00:00.000Z",
+  lastUpdated: "2026-01-01T00:00:00.000Z",
+});
+
+describe("pickRegistryEntry — scope resolution", () => {
+  test("user scope takes the user entry, ignoring project installs", () => {
+    const entries = [
+      entry("project", "1.0.0", "/proj/a"),
+      entry("user", "2.0.0"),
+      entry("project", "3.0.0", "/proj/b"),
+    ];
+    expect(pickRegistryEntry(entries, "user")?.version).toBe("2.0.0");
+  });
+
+  test("project scope prefers the entry pinned to that exact project", () => {
+    const entries = [
+      entry("user", "2.0.0"),
+      entry("project", "1.0.0", "/proj/a"),
+      entry("project", "3.0.0", "/proj/b"),
+    ];
+    expect(pickRegistryEntry(entries, "project", "/proj/b")?.version).toBe("3.0.0");
+  });
+
+  test("project scope falls back to the user entry when the project has no install", () => {
+    // This is the statusline case: installed at user scope, absent from project
+    // settings, previously surfaced as "no version" and skipped by update checks.
+    const entries = [entry("user", "2.1.2"), entry("project", "1.0.0", "/proj/other")];
+    expect(pickRegistryEntry(entries, "project", "/proj/mine")?.version).toBe("2.1.2");
+  });
+
+  test("project paths are compared resolved, not as raw strings", () => {
+    const entries = [entry("project", "4.2.0", "/proj/a/../a")];
+    expect(pickRegistryEntry(entries, "project", "/proj/a")?.version).toBe("4.2.0");
+  });
+
+  test("a local-scope entry satisfies a project lookup for the same path", () => {
+    const entries = [entry("local", "5.0.0", "/proj/a"), entry("user", "1.0.0")];
+    expect(pickRegistryEntry(entries, "project", "/proj/a")?.version).toBe("5.0.0");
+  });
+
+  test("no project path and no user entry yields undefined, not a wrong project's version", () => {
+    const entries = [entry("project", "9.9.9", "/proj/somewhere-else")];
+    expect(pickRegistryEntry(entries, "project")).toBeUndefined();
+  });
+
+  test("empty and missing entry lists are handled", () => {
+    expect(pickRegistryEntry([], "user")).toBeUndefined();
+    expect(pickRegistryEntry(undefined, "user")).toBeUndefined();
+  });
+});

package/src/__tests__/resolve-executable.test.ts

@@ -0,0 +1,42 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm, symlink, writeFile, chmod } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveExecutable } from "../utils/command-utils.js";
+
+/**
+ * resolveExecutable must treat a dangling symlink as NOT available — the exact
+ * failure mode behind a plugin's binary looking present (the symlink exists)
+ * while failing at runtime (its target is gone).
+ */
+describe("resolveExecutable — dangling symlink detection", () => {
+	let dir: string;
+	let prevPath: string | undefined;
+
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), "resolveexe-"));
+		prevPath = process.env.PATH;
+		process.env.PATH = `${dir}:${prevPath}`;
+	});
+	afterEach(async () => {
+		process.env.PATH = prevPath;
+		await rm(dir, { recursive: true, force: true });
+	});
+
+	test("a live executable resolves", async () => {
+		const bin = join(dir, "livetool");
+		await writeFile(bin, "#!/bin/sh\necho hi\n");
+		await chmod(bin, 0o755);
+		expect(await resolveExecutable("livetool")).not.toBeNull();
+	});
+
+	test("a dangling symlink resolves to null", async () => {
+		const link = join(dir, "ghosttool");
+		await symlink(join(dir, "does-not-exist"), link);
+		expect(await resolveExecutable("ghosttool")).toBeNull();
+	});
+
+	test("a missing command resolves to null", async () => {
+		expect(await resolveExecutable("definitely-not-a-real-cmd-xyz")).toBeNull();
+	});
+});

package/src/__tests__/resolver.test.ts

@@ -0,0 +1,218 @@
+import { describe, expect, test } from "bun:test";
+import {
+	dedupeBins,
+	resolveAllProfiles,
+	resolveExtends,
+	resolveProfile,
+} from "../services/resolver.js";
+import type {
+	BinRequirement,
+	ProfileManifest,
+	ProfileManifestEntry,
+} from "../types/index.js";
+
+// A binResolver that returns canned requires.bin per plugin — keeps the
+// resolver tests hermetic (no marketplace cache / filesystem).
+function fakeBinResolver(
+	table: Record<string, BinRequirement[]>,
+): (pluginId: string) => Promise<BinRequirement[]> {
+	return async (pluginId) => table[pluginId] ?? [];
+}
+
+function manifestOf(
+	profiles: Record<string, ProfileManifestEntry>,
+): ProfileManifest {
+	return { version: 2, profiles };
+}
+
+describe("dedupeBins — precedence by order", () => {
+	test("first-seen wins installer/version; later contributes only provenance", () => {
+		const claudishPin: BinRequirement = {
+			name: "claudish",
+			via: "bun",
+			package: "claudish",
+			version: "1.2.0",
+		};
+		const claudishLoose: BinRequirement = {
+			name: "claudish",
+			via: "npm",
+			package: "claudish",
+		};
+		const result = dedupeBins([
+			{ bin: claudishPin, source: "profile:x.cliTools" },
+			{ bin: claudishLoose, source: "plugin:foo@magus" },
+		]);
+		expect(result).toHaveLength(1);
+		expect(result[0]!.via).toBe("bun");
+		expect(result[0]!.version).toBe("1.2.0");
+		expect(result[0]!.sources).toEqual([
+			"profile:x.cliTools",
+			"plugin:foo@magus",
+		]);
+	});
+
+	test("a later entry fills a version the winner left unset", () => {
+		const loose: BinRequirement = { name: "tmux", via: "brew" };
+		const pinned: BinRequirement = { name: "tmux", via: "brew", version: "3.4" };
+		const result = dedupeBins([
+			{ bin: loose, source: "plugin:a" },
+			{ bin: pinned, source: "plugin:b" },
+		]);
+		expect(result[0]!.version).toBe("3.4");
+	});
+});
+
+describe("resolveExtends", () => {
+	test("inherits predefined plugins/settings under the entry's own", () => {
+		const entry: ProfileManifestEntry = {
+			name: "Custom",
+			extends: "must-have",
+			plugins: { "dev@magus": "2.9.0" },
+			settings: { effortLevel: "max" },
+		};
+		const merged = resolveExtends(entry);
+		// must-have contributes statusline@magus + multimodel@magus at "latest".
+		expect(merged.plugins!["statusline@magus"]).toBe("latest");
+		expect(merged.plugins!["multimodel@magus"]).toBe("latest");
+		// Entry's own plugin pin is preserved.
+		expect(merged.plugins!["dev@magus"]).toBe("2.9.0");
+		// Entry setting wins over the inherited one.
+		expect(merged.settings!.effortLevel).toBe("max");
+	});
+
+	test("honors an explicit @marketplace on a predefined plugin name", () => {
+		const entry: ProfileManifestEntry = {
+			name: "Growth",
+			extends: "growth-marketer",
+		};
+		const merged = resolveExtends(entry);
+		// seo/image-generate/video-editing ship on the magus-marketing channel and
+		// pin it explicitly — they must NOT be rewritten to @magus.
+		expect(merged.plugins!["seo@magus-marketing"]).toBe("latest");
+		expect(merged.plugins!["image-generate@magus-marketing"]).toBe("latest");
+		expect(merged.plugins!["video-editing@magus-marketing"]).toBe("latest");
+		expect(merged.plugins!["seo@magus"]).toBeUndefined();
+		// Bare names still default to @magus.
+		expect(merged.plugins!["browser-use@magus"]).toBe("latest");
+	});
+
+	test("no extends is a no-op", () => {
+		const entry: ProfileManifestEntry = { name: "Plain", plugins: {} };
+		expect(resolveExtends(entry)).toBe(entry);
+	});
+
+	test("unknown extends id is ignored (returns entry unchanged)", () => {
+		const entry: ProfileManifestEntry = { name: "X", extends: "nope" };
+		expect(resolveExtends(entry)).toBe(entry);
+	});
+});
+
+describe("resolveProfile", () => {
+	test("normalizes plugins, unions cliTools with plugin bins (project pin wins)", async () => {
+		const manifest = manifestOf({
+			frontend: {
+				name: "Frontend",
+				plugins: {
+					"terminal@magus": "4.1.0",
+					"dev@magus": true, // → latest
+					"old@magus": false, // → omitted
+				},
+				cliTools: { claudish: "1.2.0" },
+				env: { required: ["FIGMA_ACCESS_TOKEN"] },
+			},
+		});
+
+		const closure = await resolveProfile(manifest, "frontend", {
+			binResolver: fakeBinResolver({
+				"terminal@magus": [
+					{ name: "tmux", via: "brew", formula: "tmux" },
+					// terminal ALSO wants claudish, but the profile pinned it →
+					// profile pin must win.
+					{ name: "claudish", via: "npm", package: "claudish" },
+				],
+			}),
+		});
+
+		expect(closure.plugins).toEqual({
+			"terminal@magus": "4.1.0",
+			"dev@magus": "latest",
+		});
+		expect(closure.env.required).toEqual(["FIGMA_ACCESS_TOKEN"]);
+
+		const claudish = closure.bins.find((b) => b.name === "claudish")!;
+		expect(claudish.via).toBe("bun"); // from the cli-tools catalog, not npm
+		expect(claudish.version).toBe("1.2.0");
+		expect(claudish.sources[0]).toContain("cliTools");
+
+		const tmux = closure.bins.find((b) => b.name === "tmux")!;
+		expect(tmux.via).toBe("brew");
+		expect(tmux.sources).toContain("plugin:terminal@magus");
+	});
+
+	test("throws for an unknown profile id", async () => {
+		await expect(
+			resolveProfile(manifestOf({}), "ghost"),
+		).rejects.toThrow('Profile "ghost" not found');
+	});
+});
+
+describe("resolveAllProfiles — union", () => {
+	test("unions plugins/bins/skills/env; a pin beats latest across profiles", async () => {
+		const manifest = manifestOf({
+			frontend: {
+				name: "Frontend",
+				plugins: { "dev@magus": "latest", "terminal@magus": "4.1.0" },
+				skills: [{ name: "A", repo: "o/r", path: "skills/a" }],
+				env: { required: ["FIGMA_ACCESS_TOKEN"] },
+			},
+			backend: {
+				name: "Backend",
+				plugins: { "dev@magus": "2.9.0" }, // pin should win over "latest"
+				cliTools: { mnemex: "latest" },
+				skills: [{ name: "A", repo: "o/r", path: "skills/a" }], // dupe
+				env: { required: ["DATABASE_URL"] },
+			},
+		});
+
+		const union = await resolveAllProfiles(manifest, {
+			binResolver: fakeBinResolver({}),
+		});
+
+		expect(union.plugins["dev@magus"]).toBe("2.9.0"); // pin beat latest
+		expect(union.plugins["terminal@magus"]).toBe("4.1.0");
+		expect(union.skills).toHaveLength(1); // deduped by repo#path
+		expect(union.env.required.sort()).toEqual([
+			"DATABASE_URL",
+			"FIGMA_ACCESS_TOKEN",
+		]);
+		expect(union.bins.find((b) => b.name === "mnemex")?.via).toBe("bun");
+		expect(union.conflicts).toBeUndefined(); // latest-vs-pin isn't a conflict
+	});
+
+	test("conflicting explicit pins resolve to the higher semver, order-independent, and are reported", async () => {
+		const mk = (order: "ab" | "ba"): ProfileManifest => {
+			const a: ProfileManifestEntry = { name: "A", plugins: { "dev@magus": "2.9.0" } };
+			const b: ProfileManifestEntry = { name: "B", plugins: { "dev@magus": "2.11.0" } };
+			return manifestOf(order === "ab" ? { a, b } : { b, a });
+		};
+		const ab = await resolveAllProfiles(mk("ab"), { binResolver: fakeBinResolver({}) });
+		const ba = await resolveAllProfiles(mk("ba"), { binResolver: fakeBinResolver({}) });
+
+		// Deterministic: higher pin wins regardless of profile order.
+		expect(ab.plugins["dev@magus"]).toBe("2.11.0");
+		expect(ba.plugins["dev@magus"]).toBe("2.11.0");
+		// And the conflict is surfaced, not silent.
+		expect(ab.conflicts?.some((c) => c.includes("dev@magus"))).toBe(true);
+		expect(ba.conflicts?.some((c) => c.includes("dev@magus"))).toBe(true);
+	});
+
+	test("conflicting bin pins across profiles resolve deterministically + report", async () => {
+		const manifest = manifestOf({
+			a: { name: "A", cliTools: { claudish: "1.2.0" } },
+			b: { name: "B", cliTools: { claudish: "1.5.0" } },
+		});
+		const union = await resolveAllProfiles(manifest, { binResolver: fakeBinResolver({}) });
+		expect(union.bins.find((x) => x.name === "claudish")?.version).toBe("1.5.0");
+		expect(union.conflicts?.some((c) => c.includes("claudish"))).toBe(true);
+	});
+});

package/src/__tests__/symlink-manager.test.ts

@@ -0,0 +1,99 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm, lstat, readlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import fs from "fs-extra";
+import {
+	activateProfile,
+	activeProfile,
+	profileDir,
+} from "../services/symlink-manager.js";
+
+/** Materialize a fake profile dir with the given files. */
+async function materialize(
+	project: string,
+	name: string,
+	files: { settings?: object; mcp?: object; skills?: boolean },
+) {
+	const dir = profileDir(name, project);
+	await fs.ensureDir(dir);
+	if (files.settings) await fs.writeJson(join(dir, "settings.json"), files.settings);
+	if (files.mcp) await fs.writeJson(join(dir, "mcp.json"), files.mcp);
+	if (files.skills) await fs.ensureDir(join(dir, "skills"));
+}
+
+describe("symlink-manager", () => {
+	let project: string;
+	beforeEach(async () => {
+		project = await mkdtemp(join(tmpdir(), "symlink-"));
+	});
+	afterEach(async () => {
+		await rm(project, { recursive: true, force: true });
+	});
+
+	test("activateProfile links settings.json, .mcp.json, and skills/", async () => {
+		await materialize(project, "frontend", {
+			settings: { enabledPlugins: { "dev@magus": true } },
+			mcp: { mcpServers: {} },
+			skills: true,
+		});
+		await activateProfile("frontend", project);
+
+		// settings.json is a symlink into the profile dir
+		expect((await lstat(join(project, ".claude", "settings.json"))).isSymbolicLink()).toBe(true);
+		expect((await lstat(join(project, ".mcp.json"))).isSymbolicLink()).toBe(true);
+		expect((await lstat(join(project, ".claude", "skills"))).isSymbolicLink()).toBe(true);
+
+		// reading through the link returns the profile's content
+		const settings = await fs.readJson(join(project, ".claude", "settings.json"));
+		expect(settings.enabledPlugins["dev@magus"]).toBe(true);
+	});
+
+	test("writeJson through the settings symlink lands in the profile dir", async () => {
+		await materialize(project, "frontend", { settings: { a: 1 } });
+		await activateProfile("frontend", project);
+		await fs.writeJson(join(project, ".claude", "settings.json"), { a: 2 });
+		// The real file inside the profile dir was updated (symlink preserved).
+		expect((await lstat(join(project, ".claude", "settings.json"))).isSymbolicLink()).toBe(true);
+		expect((await fs.readJson(profileDir("frontend", project) + "/settings.json")).a).toBe(2);
+	});
+
+	test("switching repoints links and activeProfile tracks it", async () => {
+		await materialize(project, "frontend", { settings: { which: "frontend" } });
+		await materialize(project, "backend", { settings: { which: "backend" } });
+
+		await activateProfile("frontend", project);
+		expect(await activeProfile(project)).toBe("frontend");
+		expect((await fs.readJson(join(project, ".claude", "settings.json"))).which).toBe("frontend");
+
+		await activateProfile("backend", project);
+		expect(await activeProfile(project)).toBe("backend");
+		expect((await fs.readJson(join(project, ".claude", "settings.json"))).which).toBe("backend");
+	});
+
+	test("uses relative (not absolute) symlinks", async () => {
+		await materialize(project, "frontend", { settings: { a: 1 } });
+		await activateProfile("frontend", project);
+		const target = await readlink(join(project, ".claude", "settings.json"));
+		expect(target.startsWith("/")).toBe(false);
+		expect(target).toContain("_profiles");
+	});
+
+	test("a profile without skills/ creates no skills link", async () => {
+		await materialize(project, "frontend", { settings: { a: 1 } });
+		await activateProfile("frontend", project);
+		expect(await fs.pathExists(join(project, ".claude", "skills"))).toBe(false);
+	});
+
+	test("activateProfile throws if the profile isn't materialized", async () => {
+		await expect(activateProfile("ghost", project)).rejects.toThrow(
+			"not materialized",
+		);
+	});
+
+	test("activeProfile returns null when settings.json is a real file", async () => {
+		await fs.ensureDir(join(project, ".claude"));
+		await fs.writeJson(join(project, ".claude", "settings.json"), { a: 1 });
+		expect(await activeProfile(project)).toBeNull();
+	});
+});

package/src/__tests__/toolchain.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import {
+	binInstallCommand,
+	detectToolchains,
+} from "../services/toolchain.js";
+import type { ResolvedBin } from "../types/index.js";
+
+describe("binInstallCommand", () => {
+	test("bun with and without a version pin", () => {
+		expect(binInstallCommand({ name: "claudish", via: "bun", package: "claudish", version: "1.2.0" })).toBe(
+			"bun install -g claudish@1.2.0",
+		);
+		expect(binInstallCommand({ name: "claudish", via: "bun" })).toBe(
+			"bun install -g claudish",
+		);
+	});
+
+	test("npm, pip, brew, go each render correctly", () => {
+		expect(binInstallCommand({ name: "x", via: "npm", package: "x" })).toBe(
+			"npm install -g x",
+		);
+		expect(binInstallCommand({ name: "aider", via: "pip", package: "aider", version: "0.1" })).toBe(
+			"pip install aider==0.1",
+		);
+		expect(binInstallCommand({ name: "tmux", via: "brew", formula: "tmux" })).toBe(
+			"brew install tmux",
+		);
+		expect(binInstallCommand({ name: "t", via: "go", module: "github.com/x/t" })).toBe(
+			"go install github.com/x/t@latest",
+		);
+	});
+});
+
+describe("detectToolchains", () => {
+	test("groups bins by installer and reports requiredBy + presence", async () => {
+		const bins: ResolvedBin[] = [
+			{ name: "claudish", via: "bun", sources: ["a"] },
+			{ name: "mnemex", via: "bun", sources: ["b"] },
+			{ name: "tmux", via: "brew", sources: ["c"] },
+		];
+		const statuses = await detectToolchains(bins);
+		const bun = statuses.find((s) => s.name === "bun")!;
+		const brew = statuses.find((s) => s.name === "brew")!;
+		expect(bun.requiredBy.sort()).toEqual(["claudish", "mnemex"]);
+		expect(brew.requiredBy).toEqual(["tmux"]);
+		// bun/brew are bootstrappable; the field is populated.
+		expect(bun.bootstrap).toContain("bun.sh");
+		expect(typeof bun.present).toBe("boolean");
+		// stable order: bun before brew
+		expect(statuses.map((s) => s.name)).toEqual(["bun", "brew"]);
+	});
+
+	test("returns only toolchains actually needed (empty for no bins)", async () => {
+		expect(await detectToolchains([])).toEqual([]);
+	});
+});

package/src/cli/claude.ts

@@ -0,0 +1,21 @@
+/**
+ * `claudeup claude [args...]` — prerunner mode.
+ *
+ * Runs plugin/marketplace update & migration checks (1h cache, or `-f`/`--force`
+ * to bypass), then execs `claude` with the remaining args. Returns claude's exit
+ * code so the caller can propagate it.
+ */
+
+import { prerunClaude } from "../prerunner/index.js";
+
+export async function runClaudeCommand(claudeArgs: string[]): Promise<number> {
+	const forceUpdate =
+		claudeArgs.includes("--force") || claudeArgs.includes("-f");
+
+	// Remove prerunner-specific flags before passing args to claude.
+	const filteredArgs = claudeArgs.filter(
+		(arg) => arg !== "--force" && arg !== "-f",
+	);
+
+	return prerunClaude(filteredArgs, { force: forceUpdate });
+}