claudeup 4.42.1 → 5.0.1

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/package.json

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

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

@@ -87,6 +87,11 @@ describe("loadProjectDotenv", () => {
 		expect(r.warnings).toHaveLength(1);
 		expect(r.warnings[0]).toContain(".env");
 		expect(r.warnings[0]).toContain("named pipe");
+		// The warning must give the real reason — the open blocks with no writer.
+		// It must NOT claim reading would steal another process's secrets: a
+		// 1Password pipe re-serves on every open, so that rationale is false.
+		expect(r.warnings[0]).toContain("blocks");
+		expect(r.warnings[0]).not.toContain("consume");
 	});
 
 	it("skips a .env that is a FIFO directly, and warns", () => {

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[] = [

package/src/__tests__/update-apply.test.ts

@@ -0,0 +1,223 @@
+/**
+ * Regression tests for the `claudeup update` APPLY path.
+ *
+ * Every defect a multi-model review found in this feature lived here, in the
+ * half that had no coverage, while the pure planner beside it had forty tests.
+ * These lock the apply path's contract so that gap cannot silently reopen.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+import { type PluginApplyDeps, applyPlugins } from "../cli/update.js";
+import type { PluginScope } from "../services/claude-cli.js";
+import type { PluginUpdateItem } from "../services/update-plan.js";
+
+const PROJECT = "/tmp/project";
+
+/** Records every call, and lets a test dictate what the registry reads back. */
+function stubDeps(
+	installedAfter: string | null | ((scope: PluginScope) => string | null),
+) {
+	const saved: Array<{ id: string; version: string; scope: PluginScope }> = [];
+	const updated: Array<{ id: string; scope: PluginScope }> = [];
+	const repaired: Array<{ id: string; scope: PluginScope }> = [];
+
+	const deps: PluginApplyDeps = {
+		update: mock(async (id: string, scope: PluginScope) => {
+			updated.push({ id, scope });
+		}),
+		repair: mock(async (id: string, scope: PluginScope) => {
+			repaired.push({ id, scope });
+		}),
+		readInstalled: mock(async (_id: string, scope: PluginScope) =>
+			typeof installedAfter === "function"
+				? installedAfter(scope)
+				: installedAfter,
+		),
+		saveInstalled: mock(
+			async (id: string, version: string, scope: PluginScope) => {
+				saved.push({ id, version, scope });
+			},
+		),
+	};
+	return { deps, saved, updated, repaired };
+}
+
+function item(over: Partial<PluginUpdateItem>): PluginUpdateItem {
+	return {
+		pluginId: "dev@magus",
+		pinned: "latest",
+		installed: "1.0.0",
+		available: "2.0.0",
+		target: "2.0.0",
+		action: "update",
+		scopes: ["project"],
+		...over,
+	};
+}
+
+let logs: string[];
+beforeEach(() => {
+	logs = [];
+	// biome-ignore lint/suspicious/noExplicitAny: test double
+	console.log = ((...a: unknown[]) => logs.push(a.join(" "))) as any;
+	// biome-ignore lint/suspicious/noExplicitAny: test double
+	console.warn = ((...a: unknown[]) => logs.push(a.join(" "))) as any;
+});
+
+describe("what gets RECORDED is what got installed", () => {
+	test("records the version read back, not the version we asked for", async () => {
+		// `claude plugin install` accepts no version — it installs the newest.
+		// Recording `target` instead of the read-back made the registry claim a
+		// version that was never on disk.
+		const { deps, saved } = stubDeps("9.9.9");
+		await applyPlugins([item({ target: "2.0.0" })], PROJECT, deps);
+		expect(saved).toEqual([
+			{ id: "dev@magus", version: "9.9.9", scope: "project" },
+		]);
+	});
+
+	test("an exact pin the installer could not honour is reported, not hidden", async () => {
+		const { deps, saved } = stubDeps("9.9.9");
+		const result = await applyPlugins(
+			[item({ pinned: "4.6.1", target: "4.6.1" })],
+			PROJECT,
+			deps,
+		);
+		// The pin is NOT written as if satisfied...
+		expect(saved).toEqual([
+			{ id: "dev@magus", version: "9.9.9", scope: "project" },
+		]);
+		// ...and the shortfall is surfaced to the caller.
+		expect(result.mismatches).toEqual([
+			{
+				pluginId: "dev@magus",
+				pinned: "4.6.1",
+				actual: "9.9.9",
+				scope: "project",
+			},
+		]);
+	});
+
+	test("a satisfied exact pin produces no mismatch", async () => {
+		const { deps } = stubDeps("4.6.1");
+		const result = await applyPlugins(
+			[item({ pinned: "4.6.1", target: "4.6.1" })],
+			PROJECT,
+			deps,
+		);
+		expect(result.mismatches).toEqual([]);
+	});
+
+	test("a 'latest' pin never counts as a mismatch", async () => {
+		const { deps } = stubDeps("9.9.9");
+		const result = await applyPlugins(
+			[item({ pinned: "latest", target: "2.0.0" })],
+			PROJECT,
+			deps,
+		);
+		expect(result.mismatches).toEqual([]);
+	});
+
+	test("nothing is recorded when the registry has no version to read back", async () => {
+		// Writing a guess here would be the same fabrication in another costume.
+		const { deps, saved } = stubDeps(null);
+		await applyPlugins([item({})], PROJECT, deps);
+		expect(saved).toEqual([]);
+	});
+});
+
+describe("scope handling", () => {
+	test("a fresh install goes to project scope only", async () => {
+		const { deps, updated } = stubDeps("2.0.0");
+		await applyPlugins(
+			[item({ action: "install", installed: null, scopes: [] })],
+			PROJECT,
+			deps,
+		);
+		expect(updated).toEqual([{ id: "dev@magus", scope: "project" }]);
+	});
+
+	test("every outdated scope is updated AND recorded separately", async () => {
+		const { deps, updated, saved } = stubDeps((scope) =>
+			scope === "user" ? "2.0.0" : "1.5.0",
+		);
+		await applyPlugins([item({ scopes: ["user", "project"] })], PROJECT, deps);
+		expect(updated).toEqual([
+			{ id: "dev@magus", scope: "user" },
+			{ id: "dev@magus", scope: "project" },
+		]);
+		// Each scope records ITS OWN read-back, never one shared value.
+		expect(saved).toEqual([
+			{ id: "dev@magus", version: "2.0.0", scope: "user" },
+			{ id: "dev@magus", version: "1.5.0", scope: "project" },
+		]);
+	});
+
+	test("a repair uses repairPlugin, not a plain install", async () => {
+		// A content-stale plugin has no version bump, so `install` is a no-op that
+		// reports success — only uninstall+install refreshes the files.
+		const { deps, repaired, updated } = stubDeps("1.0.0");
+		await applyPlugins([item({ action: "repair" })], PROJECT, deps);
+		expect(repaired).toEqual([{ id: "dev@magus", scope: "project" }]);
+		expect(updated).toEqual([]);
+	});
+});
+
+describe("what is skipped", () => {
+	test("'current' and 'unknown' items are never touched", async () => {
+		const { deps, updated, saved } = stubDeps("1.0.0");
+		await applyPlugins(
+			[
+				item({ action: "current", scopes: [] }),
+				item({ pluginId: "b@magus", action: "unknown", scopes: [] }),
+			],
+			PROJECT,
+			deps,
+		);
+		expect(updated).toEqual([]);
+		expect(saved).toEqual([]);
+	});
+
+	test("an 'unknown' plugin is not installed on a guess", async () => {
+		// It is unknown because the catalog could not be reached. Acting on that
+		// would be picking a version at random.
+		const { deps, updated } = stubDeps("1.0.0");
+		await applyPlugins(
+			[item({ action: "unknown", target: null, scopes: ["project"] })],
+			PROJECT,
+			deps,
+		);
+		expect(updated).toEqual([]);
+	});
+});
+
+describe("failure handling", () => {
+	test("a failing plugin is reported, and the rest still run", async () => {
+		const { deps, updated } = stubDeps("2.0.0");
+		deps.update = mock(async (id: string, scope: PluginScope) => {
+			if (id === "bad@magus") throw new Error("network down");
+			updated.push({ id, scope });
+		});
+
+		const result = await applyPlugins(
+			[item({ pluginId: "bad@magus" }), item({ pluginId: "good@magus" })],
+			PROJECT,
+			deps,
+		);
+
+		expect(result.failed).toEqual(["bad@magus"]);
+		expect(result.ok).toBe(1);
+		expect(updated).toEqual([{ id: "good@magus", scope: "project" }]);
+	});
+
+	test("a scope that threw records nothing for that plugin", async () => {
+		// Half-applied state must not be recorded as if it succeeded.
+		const { deps, saved } = stubDeps("2.0.0");
+		deps.update = mock(async () => {
+			throw new Error("boom");
+		});
+		const result = await applyPlugins([item({})], PROJECT, deps);
+		expect(saved).toEqual([]);
+		expect(result.ok).toBe(0);
+	});
+});