claudeup 4.42.0 → 5.0.0

package/README.md

@@ -13,9 +13,13 @@ npm install -g claudeup  # also works
 Updates go through claudeup itself, not the package manager:
 
 ```bash
-claudeup update
+claudeup upgrade
 ```
 
+`upgrade` advances **claudeup**. `update` advances **your dependencies** — the
+plugins, CLI tools and skills your profile declares. Same split as every package
+manager, so the two are never confused.
+
 You get a self-contained binary for your platform (an `optionalDependencies`
 package gated on `os`/`cpu`). On a platform without a prebuilt binary the
 launcher falls back to running from source under Bun, so the install still works.
@@ -35,23 +39,89 @@ Good for making a teammate's machine match yours. This is the
 claudeup                    Open the interactive TUI
 
 install [profile]           Install a profile's plugins, binaries, skills and
-                            env, then activate it. No argument = every profile.
+                            env at the manifest's PINNED versions, then activate
+                            it. No argument = every profile.
   --check                   Report drift only, write nothing (CI gate)
   --yes, -y                 Skip the confirmation prompt
   --force                   Discard unsynced local edits instead of refusing
+update [profile]            Bring the ACTIVE profile up to date: install what it
+                            declares but this machine lacks, and advance every
+                            "latest" pin to the newest published version.
+  --check                   Report only, write nothing (exits 1 if anything is
+                            missing or known to be behind)
+  --yes, -y                 Skip the confirmation prompt
 profile list                Show every profile; ● marks the active one
 profile show <name>         Print a profile's fully resolved closure
 profile switch <name>       Repoint the active profile — offline, no reinstall
+profile init                Write .claude/profiles.json from this project's setup
 profile sync                Promote local edits back into .claude/profiles.json
 doctor [--fix]              Check binary deps, profile symlinks, conventions
 
 claude [args...]            Check for plugin updates (1h cache), then run claude
   --force, -f               Force the update check
-update                      Update claudeup itself
+upgrade                     Update claudeup itself
 --version, -v               Version + update check
 --help, -h                  This list
 ```
 
+### install vs update
+
+They differ in one thing: whether the pins are allowed to move.
+
+| | `install` | `update` |
+|---|---|---|
+| Versions | exactly what the manifest pins | advances every `"latest"` pin |
+| Scope | every profile (or the one named) | the **active** profile |
+| Also does | materializes + activates the profile | nothing to the manifest |
+
+Both install whatever the profile declares and this machine lacks, so `update`
+covers the "I ticked it but never installed it" case on its own.
+
+**This is dependency management, not a package manager.** There is no resolver,
+no lockfile and no version negotiation. The job is: everything the profile
+declares is installed, and current.
+
+That matters for exact pins. `claude plugin install` takes no version argument —
+it installs whatever the marketplace publishes now — so a pin naming anything
+else cannot be satisfied. `update` plans against the version it can actually
+get, notes the shortfall, and moves on:
+
+```
+  dev@magus   = 9.9.9  (manifest pins 4.6.1; the marketplace offers only 9.9.9)
+```
+
+It records what actually landed, never the pin, and it does **not** fail over
+the difference — an unsatisfiable pin is a standing property of the manifest,
+not something a given run did wrong. Pin drift is gated where it always was:
+`claudeup install --check` with `strictVersions` in the manifest.
+
+**`update` only ever moves forward.** Nothing here can downgrade — the installer
+takes no version — so an install that is already ahead of what the marketplace
+publishes is left alone rather than dragged back. A plan that tried would emit a
+step that runs, reports success, changes nothing, and reappears on every
+subsequent run.
+
+`--check` fails on things that are **missing or known to be behind**. It
+deliberately does not fail on the two items that get re-fetched every run
+regardless: an already-installed skill (a manifest skill ref carries no content
+hash, so there is nothing to compare) and a present unpinned binary (no version
+probe exists, only present/absent). A gate that can never pass gets switched
+off, so it only fires on real drift.
+
+Neither command needs a manifest to exist first. In a repo without
+`.claude/profiles.json`, both offer to write one describing the project as it
+stands — that is `claudeup profile init`, which you can also run on its own.
+Adoption reads the project's own `.claude/settings.json`; if that enables
+nothing it falls back to your user-scope settings and says so, because the file
+is meant to be committed and one machine's global set is not a team contract.
+Machine-only keys are stripped, and any settings value naming a path under your
+home directory is flagged for review.
+
+`--yes` alone will **not** create a manifest. It means "don't ask me about the
+command I ran", and someone running `claudeup update --yes` in CI did not ask to
+author their team's committed contract. Creating it needs a human at the prompt,
+or `claudeup profile init`.
+
 `claudeup doctor` exits non-zero when it finds a problem, so it works as a CI
 check. So does `claudeup install --check`.
 

package/bin/claudeup.js

@@ -6,6 +6,11 @@
  * optionalDependency (claudeup-<platform>-<arch>) — that binary embeds the Bun
  * runtime, so it runs without Bun installed. Falls back to running from source
  * via Bun for dev checkouts and unsupported platforms.
+ *
+ * Set CLAUDEUP_NO_BINARY=1 to skip the prebuilt binary and force the source
+ * path. That escape hatch exists because the launcher PREFERS the binary: when
+ * a shipped binary cannot start on a given machine, without it claudeup is a
+ * hard block rather than a slow start.
  */
 
 import { spawnSync } from "node:child_process";
@@ -18,7 +23,8 @@ const require = createRequire(import.meta.url);
 const args = process.argv.slice(2);
 const { platform, arch } = process;
 
-// 1. Prefer the prebuilt platform binary.
+// 1. Prefer the prebuilt platform binary, unless the source path is forced.
+const forceSource = process.env.CLAUDEUP_NO_BINARY === "1";
 const pkgName = `claudeup-${platform}-${arch}`;
 let binaryPath = null;
 try {
@@ -29,9 +35,16 @@ try {
 	// optional dep not installed for this platform — fall through
 }
 
-if (binaryPath) {
+if (binaryPath && !forceSource) {
 	const result = spawnSync(binaryPath, args, { stdio: "inherit" });
-	process.exit(result.status ?? 0);
+	// A binary that could not be executed AT ALL (ENOENT, EACCES, bad arch)
+	// leaves status null, and `status ?? 0` then reported SUCCESS for a run that
+	// never happened — the worst answer available. Only trust the status when the
+	// process actually ran; otherwise say so and fall through to the source path.
+	if (!result.error) process.exit(result.status ?? 0);
+	console.error(
+		`claudeup: prebuilt binary could not start (${result.error.message}); falling back to source.`,
+	);
 }
 
 // 2. Fallback: run from source via Bun.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeup",
-  "version": "4.42.0",
+  "version": "5.0.0",
   "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": {
-    "claudeup-darwin-arm64": "4.42.0",
-    "claudeup-darwin-x64": "4.42.0",
-    "claudeup-linux-x64": "4.42.0"
+    "claudeup-darwin-arm64": "5.0.0",
+    "claudeup-darwin-x64": "5.0.0",
+    "claudeup-linux-x64": "5.0.0"
   }
 }

package/scripts/build-binaries.ts

@@ -14,6 +14,16 @@
  * only the one matching the host os/cpu, and bin/claudeup.js execs it.
  *
  * Hard constraint: claudeup pins @opentui 0.1.x — 0.4.x breaks --compile.
+ *
+ * Hard constraint: the two --no-compile-autoload flags below must stay. A Bun
+ * standalone executable autoloads .env and bunfig.toml from its CURRENT
+ * DIRECTORY by default, and claudeup reads neither on purpose. Bun 1.4.0 dies
+ * in the .env path when that file is a symlink pointing at a FIFO — exactly how
+ * 1Password serves secrets into a git worktree — exiting 1 with nothing on
+ * stdout or stderr, because the crash lands before any JS runs and therefore
+ * before any error handler exists. A FIFO also hands its bytes to whoever opens
+ * it first, so an autoloading claudeup can swallow the secrets a dev server was
+ * waiting for. Dropping the flags re-arms both failures.
  */
 
 import { $ } from "bun";
@@ -53,7 +63,8 @@ for (const t of TARGETS) {
 	await mkdir(path.join(outDir, "bin"), { recursive: true });
 
 	console.log(`Building ${pkgName} (${t.bunTarget})…`);
-	await $`bun build --compile --target=${t.bunTarget} ${entry} --outfile ${binPath}`;
+	// The --no-compile-autoload flags are load-bearing; see the header.
+	await $`bun build --compile --no-compile-autoload-dotenv --no-compile-autoload-bunfig --target=${t.bunTarget} ${entry} --outfile ${binPath}`;
 
 	// Platform package: os/cpu-restricted, ships only the binary, declares NO
 	// `bin` (the main package's launcher resolves and execs bin/claudeup).

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

@@ -63,3 +63,49 @@ describe("route() dispatch", () => {
 		expect(typeof mod.route).toBe("function");
 	});
 });
+
+describe("update / upgrade split", () => {
+	// `update` used to self-update claudeup. 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 `claudeup upgrade`, not `claudeup 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("claudeup upgrade");
+			expect(out).not.toContain("Run: claudeup 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 claudeup ITSELF");
+		expect(help).toContain("profile init");
+		// The old wording sent people to `update` for a self-update.
+		expect(help).not.toContain("update             Update claudeup itself");
+	});
+});

package/src/__tests__/dotenv.test.ts

@@ -0,0 +1,190 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadProjectDotenv, parseDotenv } from "../services/dotenv";
+
+function mkfifo(path: string): void {
+	const r = spawnSync("mkfifo", [path]);
+	if (r.status !== 0) {
+		throw new Error(`mkfifo failed: ${r.stderr?.toString() ?? "unknown"}`);
+	}
+}
+
+describe("loadProjectDotenv", () => {
+	let dir: string;
+
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), "claudeup-dotenv-"));
+	});
+
+	afterEach(async () => {
+		await rm(dir, { recursive: true, force: true });
+	});
+
+	it("loads a regular .env", async () => {
+		await writeFile(join(dir, ".env"), "FOO=bar\nBAZ=qux\n");
+		const env: Record<string, string | undefined> = {};
+
+		const r = loadProjectDotenv(dir, env);
+
+		expect(env.FOO).toBe("bar");
+		expect(env.BAZ).toBe("qux");
+		expect(r.loaded).toEqual([".env"]);
+		expect(r.warnings).toEqual([]);
+	});
+
+	it("never overwrites a variable already in the environment", async () => {
+		await writeFile(join(dir, ".env"), "FOO=from-file\n");
+		const env: Record<string, string | undefined> = { FOO: "from-shell" };
+
+		const r = loadProjectDotenv(dir, env);
+
+		expect(env.FOO).toBe("from-shell");
+		expect(r.applied).not.toContain("FOO");
+	});
+
+	it("lets .env.local win over .env", async () => {
+		await writeFile(join(dir, ".env"), "FOO=base\nONLY_BASE=yes\n");
+		await writeFile(join(dir, ".env.local"), "FOO=override\n");
+		const env: Record<string, string | undefined> = {};
+
+		const r = loadProjectDotenv(dir, env);
+
+		expect(env.FOO).toBe("override");
+		expect(env.ONLY_BASE).toBe("yes");
+		expect(r.loaded).toEqual([".env", ".env.local"]);
+	});
+
+	it("says nothing when there is no .env at all", () => {
+		const env: Record<string, string | undefined> = {};
+
+		const r = loadProjectDotenv(dir, env);
+
+		expect(r.loaded).toEqual([]);
+		expect(r.warnings).toEqual([]);
+		expect(env).toEqual({});
+	});
+
+	// The regression this whole module exists for. claudeup 4.41.0 shipped a
+	// binary whose embedded Bun autoloaded .env and aborted on this exact shape:
+	// exit 1, nothing on stdout, nothing on stderr, in every git worktree where
+	// 1Password serves secrets through a pipe.
+	//
+	// Note the failure mode if this ever regresses: opening a FIFO with no writer
+	// BLOCKS, so a broken loader hangs here rather than failing an assertion.
+	// A timeout on this test is the same bug, reported differently.
+	it("skips a .env that is a symlink to a FIFO, and warns", async () => {
+		mkfifo(join(dir, "secrets-pipe"));
+		await symlink(join(dir, "secrets-pipe"), join(dir, ".env"));
+		const env: Record<string, string | undefined> = {};
+
+		const r = loadProjectDotenv(dir, env);
+
+		expect(r.loaded).toEqual([]);
+		expect(env).toEqual({});
+		expect(r.warnings).toHaveLength(1);
+		expect(r.warnings[0]).toContain(".env");
+		expect(r.warnings[0]).toContain("named pipe");
+	});
+
+	it("skips a .env that is a FIFO directly, and warns", () => {
+		mkfifo(join(dir, ".env"));
+		const env: Record<string, string | undefined> = {};
+
+		const r = loadProjectDotenv(dir, env);
+
+		expect(r.loaded).toEqual([]);
+		expect(r.warnings).toHaveLength(1);
+		expect(r.warnings[0]).toContain("named pipe");
+	});
+
+	it("follows a symlink that points at a regular file", async () => {
+		await writeFile(join(dir, "real-env"), "FOO=bar\n");
+		await symlink(join(dir, "real-env"), join(dir, ".env"));
+		const env: Record<string, string | undefined> = {};
+
+		const r = loadProjectDotenv(dir, env);
+
+		expect(env.FOO).toBe("bar");
+		expect(r.loaded).toEqual([".env"]);
+		expect(r.warnings).toEqual([]);
+	});
+
+	it("warns instead of throwing on a dangling symlink", async () => {
+		await symlink(join(dir, "nothing-here"), join(dir, ".env"));
+		const env: Record<string, string | undefined> = {};
+
+		const r = loadProjectDotenv(dir, env);
+
+		expect(r.loaded).toEqual([]);
+		expect(r.warnings).toHaveLength(1);
+		expect(r.warnings[0]).toContain("does not resolve");
+	});
+
+	it("skips a .env that is a directory, and warns", async () => {
+		await mkdir(join(dir, ".env"));
+		const env: Record<string, string | undefined> = {};
+
+		const r = loadProjectDotenv(dir, env);
+
+		expect(r.loaded).toEqual([]);
+		expect(r.warnings[0]).toContain("directory");
+	});
+
+	it("loads what it can from a file with unparseable lines", async () => {
+		await writeFile(
+			join(dir, ".env"),
+			"this is not a pair\nFOO=bar\n=novalue\n",
+		);
+		const env: Record<string, string | undefined> = {};
+
+		const r = loadProjectDotenv(dir, env);
+
+		expect(env.FOO).toBe("bar");
+		expect(r.warnings).toEqual([]);
+	});
+});
+
+describe("parseDotenv", () => {
+	it("ignores comments and blank lines", () => {
+		expect(parseDotenv("# note\n\nFOO=bar\n")).toEqual({ FOO: "bar" });
+	});
+
+	it("strips an export prefix", () => {
+		expect(parseDotenv("export FOO=bar\n")).toEqual({ FOO: "bar" });
+	});
+
+	it("strips surrounding quotes", () => {
+		expect(parseDotenv(`FOO="bar"\nBAZ='qux'\n`)).toEqual({
+			FOO: "bar",
+			BAZ: "qux",
+		});
+	});
+
+	it("expands escapes in double quotes but not single quotes", () => {
+		expect(parseDotenv(`A="one\\ntwo"\nB='one\\ntwo'\n`)).toEqual({
+			A: "one\ntwo",
+			B: "one\\ntwo",
+		});
+	});
+
+	it("drops a trailing comment from an unquoted value", () => {
+		expect(parseDotenv("FOO=bar # why\n")).toEqual({ FOO: "bar" });
+	});
+
+	it("keeps a # that is part of a quoted value", () => {
+		expect(parseDotenv(`FOO="bar # why"\n`)).toEqual({ FOO: "bar # why" });
+	});
+
+	it("keeps an = that appears inside a value", () => {
+		expect(parseDotenv("URL=postgres://u:p@h/db?a=b\n")).toEqual({
+			URL: "postgres://u:p@h/db?a=b",
+		});
+	});
+
+	it("rejects a key that is not a valid identifier", () => {
+		expect(parseDotenv("not-a-key=x\nOK=y\n")).toEqual({ OK: "y" });
+	});
+});

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

@@ -0,0 +1,177 @@
+import { describe, expect, test } from "bun:test";
+import {
+	buildAdoptedProfile,
+	findMachineSpecificPaths,
+} from "../services/profile-adopt.js";
+
+const NOW = "2026-08-27T00:00:00.000Z";
+
+describe("buildAdoptedProfile", () => {
+	test("adopts enabled plugins as 'latest', never as the installed version", () => {
+		// Pinning whatever a machine drifted to would turn one developer's
+		// accident into the team's contract.
+		const entry = buildAdoptedProfile({
+			enabledPlugins: { "dev@magus": true, "mnemex@magus": true },
+			settings: {},
+			mcpServers: {},
+			now: NOW,
+		});
+		expect(entry.plugins).toEqual({
+			"dev@magus": "latest",
+			"mnemex@magus": "latest",
+		});
+	});
+
+	test("skips disabled plugins", () => {
+		const entry = buildAdoptedProfile({
+			enabledPlugins: { "dev@magus": true, "gtd@magus": false },
+			settings: {},
+			mcpServers: {},
+			now: NOW,
+		});
+		expect(Object.keys(entry.plugins ?? {})).toEqual(["dev@magus"]);
+	});
+
+	test("skips an id with no marketplace — it cannot be reinstalled elsewhere", () => {
+		const entry = buildAdoptedProfile({
+			enabledPlugins: { "dev@magus": true, "some-local-thing": true },
+			settings: {},
+			mcpServers: {},
+			now: NOW,
+		});
+		expect(Object.keys(entry.plugins ?? {})).toEqual(["dev@magus"]);
+	});
+
+	test("derives the marketplace each plugin id names", () => {
+		const entry = buildAdoptedProfile({
+			enabledPlugins: { "dev@magus": true },
+			settings: {},
+			mcpServers: {},
+			now: NOW,
+		});
+		expect(entry.marketplaces?.magus).toEqual({
+			source: "github",
+			repo: "MadAppGang/magus",
+		});
+	});
+
+	test("drops enabledPlugins from settings — the plugins map expresses it", () => {
+		// Carrying both would let them disagree; materialization regenerates
+		// enabledPlugins from the plugins map.
+		const entry = buildAdoptedProfile({
+			enabledPlugins: { "dev@magus": true },
+			settings: {
+				enabledPlugins: { "dev@magus": true },
+				enableAllProjectMcpServers: true,
+			},
+			mcpServers: {},
+			now: NOW,
+		});
+		expect(entry.settings).toEqual({ enableAllProjectMcpServers: true });
+	});
+
+	test("carries MCP servers over verbatim", () => {
+		const servers = {
+			"chrome-devtools": { command: "npx", args: ["-y", "x"] },
+		};
+		const entry = buildAdoptedProfile({
+			enabledPlugins: { "dev@magus": true },
+			settings: {},
+			mcpServers: servers,
+			now: NOW,
+		});
+		expect(entry.mcpServers).toEqual(servers);
+	});
+
+	test("omits empty settings and mcpServers rather than writing empty objects", () => {
+		const entry = buildAdoptedProfile({
+			enabledPlugins: { "dev@magus": true },
+			settings: {},
+			mcpServers: {},
+			now: NOW,
+		});
+		expect(entry.settings).toBeUndefined();
+		expect(entry.mcpServers).toBeUndefined();
+	});
+
+	test("strips installedPluginVersions — that is machine state, not a contract", () => {
+		// Committing it publishes one developer's install state as the team's
+		// contract, and it is stale the moment anyone updates.
+		const entry = buildAdoptedProfile({
+			enabledPlugins: { "dev@magus": true },
+			settings: {
+				installedPluginVersions: { "dev@magus": "4.6.1" },
+				enableAllProjectMcpServers: true,
+			},
+			mcpServers: {},
+			now: NOW,
+		});
+		expect(entry.settings).toEqual({ enableAllProjectMcpServers: true });
+	});
+
+	test("omits settings entirely when only machine keys were present", () => {
+		const entry = buildAdoptedProfile({
+			enabledPlugins: { "dev@magus": true },
+			settings: {
+				enabledPlugins: { "dev@magus": true },
+				installedPluginVersions: { "dev@magus": "4.6.1" },
+			},
+			mcpServers: {},
+			now: NOW,
+		});
+		expect(entry.settings).toBeUndefined();
+	});
+
+	test("does not mutate the caller's settings object", () => {
+		const settings = {
+			installedPluginVersions: { "dev@magus": "4.6.1" },
+			other: 1,
+		};
+		buildAdoptedProfile({
+			enabledPlugins: { "dev@magus": true },
+			settings,
+			mcpServers: {},
+			now: NOW,
+		});
+		expect(settings.installedPluginVersions).toEqual({ "dev@magus": "4.6.1" });
+	});
+
+	test("is deterministic when the clock is injected", () => {
+		const input = {
+			enabledPlugins: { "dev@magus": true },
+			settings: {},
+			mcpServers: {},
+			now: NOW,
+		};
+		expect(buildAdoptedProfile(input)).toEqual(buildAdoptedProfile(input));
+		expect(buildAdoptedProfile(input).createdAt).toBe(NOW);
+	});
+});
+
+describe("findMachineSpecificPaths", () => {
+	const HOME = "/Users/someone";
+
+	test("flags a home-directory path nested in an array", () => {
+		// Not stripped — an additionalDirectories list is often genuinely wanted —
+		// but surfaced, because it will not resolve on a teammate's machine.
+		expect(
+			findMachineSpecificPaths(
+				{ permissions: { additionalDirectories: ["../sibling", `${HOME}/x`] } },
+				HOME,
+			),
+		).toEqual([`permissions.additionalDirectories[1] = ${HOME}/x`]);
+	});
+
+	test("relative paths are not flagged", () => {
+		expect(
+			findMachineSpecificPaths(
+				{ permissions: { additionalDirectories: ["../magus", "./local"] } },
+				HOME,
+			),
+		).toEqual([]);
+	});
+
+	test("returns nothing rather than guessing when HOME is unset", () => {
+		expect(findMachineSpecificPaths({ a: `${HOME}/x` }, "")).toEqual([]);
+	});
+});

package/src/__tests__/toolchain.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import {
 	binInstallCommand,
+	binUpgradeCommand,
 	detectToolchains,
 } from "../services/toolchain.js";
 import type { ResolvedBin } from "../types/index.js";
@@ -31,6 +32,36 @@ describe("binInstallCommand", () => {
 	});
 });
 
+describe("binUpgradeCommand", () => {
+	test("brew and pip do NOT reuse their install command", () => {
+		// This is the whole reason the function exists: `brew install` on an
+		// installed formula prints "already installed" and changes nothing, and
+		// `pip install` without --upgrade does the same. Reusing them would let
+		// `claudeup update` report success while advancing nothing.
+		expect(binUpgradeCommand({ name: "tmux", via: "brew", formula: "tmux" })).toBe(
+			"brew upgrade tmux",
+		);
+		expect(binUpgradeCommand({ name: "aider", via: "pip", package: "aider" })).toBe(
+			"pip install --upgrade aider",
+		);
+	});
+
+	test("bun and npm state @latest explicitly, so the printed command reads true", () => {
+		expect(binUpgradeCommand({ name: "claudish", via: "bun" })).toBe(
+			"bun install -g claudish@latest",
+		);
+		expect(binUpgradeCommand({ name: "x", via: "npm", package: "x" })).toBe(
+			"npm install -g x@latest",
+		);
+	});
+
+	test("go installs the module at latest", () => {
+		expect(
+			binUpgradeCommand({ 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[] = [