claudeup 4.30.0 → 4.32.0

package/README.md

@@ -1,128 +1,134 @@
 # claudeup
 
-TUI tool for managing Claude Code plugins, MCPs, and configuration.
+Manage a Claude Code setup — plugins, MCP servers, skills, CLI tools and the
+binaries plugins depend on — from a TUI, a CLI, or a committed team manifest.
 
-## Installation
+## Install
 
 ```bash
-# Using pnpm
-pnpm add -g claudeup
-
-# Using pnpx (no install)
-pnpx claudeup
-
-# Using npm
-npm install -g claudeup
-
-# Using Bun
-bun add -g claudeup
+bun add -g claudeup      # recommended
+npm install -g claudeup  # also works
 ```
 
-## Features
-
-### 1. MCP Server Setup
-Configure Model Context Protocol servers with a curated list:
-- **File System** - Read/write files, search directories
-- **Database** - SQLite, PostgreSQL connections
-- **Developer Tools** - GitHub, GitLab, Chrome DevTools, Puppeteer
-- **API & Web** - HTTP requests, Brave Search
-- **Productivity** - Google Drive, Slack, Memory
-- **AI & Intelligence** - Claude Context (semantic search), Sequential Thinking
-
-### 2. Plugin Marketplaces
-Add official and community plugin marketplaces:
-- **Anthropic Official** - Official Claude Code plugins
-- **MadAppGang** - Frontend, Backend, Code Analysis plugins
-
-### 3. Manage Plugins
-Install and configure plugins from added marketplaces:
-- Frontend Development (React/TypeScript)
-- Code Analysis (Deep investigation)
-- Bun Backend (TypeScript backend)
-- Orchestration (Multi-agent patterns)
-- Agent Development (Create agents)
-
-### 4. Status Line Configuration
-Configure the Claude Code status line with presets:
-- Minimal, Standard, Detailed
-- Git-aware, Token-focused
-- Time-tracking, Developer
-
-## Usage
+Updates go through claudeup itself, not the package manager:
 
 ```bash
-# Launch TUI
-claudeup
-
-# Or with npx
-npx claudeup
+claudeup update
 ```
 
-### Navigation
-- `↑/↓` or `j/k` - Move selection
-- `Enter` - Select item
-- `Escape/q` - Go back / Exit
-- `?` - Show help
-- `1-4` - Quick jump to screens
+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.
 
-## Development
+## Two ways to use it
 
-```bash
-# Install dependencies
-pnpm install
+**Interactive** — run `claudeup` with no arguments for the TUI. Good for
+exploring what is available and toggling things on one machine.
 
-# Build
-pnpm build
+**Declarative** — commit a `.claude/profiles.json` and run `claudeup install`.
+Good for making a teammate's machine match yours. This is the
+[team configuration guide](docs/team-configuration.md).
 
-# Run in development
-pnpm start:bun  # With Bun
-pnpm start      # With Node
-```
+## Commands
 
-## Configuration Files
+```
+claudeup                    Open the interactive TUI
+
+install [profile]           Install a profile's plugins, binaries, skills and
+                            env, 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
+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 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
+--version, -v               Version + update check
+--help, -h                  This list
+```
 
-claudeup modifies these Claude Code configuration files:
+`claudeup doctor` exits non-zero when it finds a problem, so it works as a CI
+check. So does `claudeup install --check`.
 
-- `.claude/settings.json` - Shared settings (plugins, marketplaces)
-- `.claude/settings.local.json` - Local settings (MCP servers, allowMcp)
+## What the TUI covers
 
-## Release Process
+| Screen | What it manages |
+|---|---|
+| Plugins | Install, enable, disable; shows version changes and newly installed plugins |
+| Skills | Browse and install skills from configured skill repos |
+| MCP | Add MCP servers from a curated catalog |
+| Settings | Claude Code settings, from a catalog of known keys |
+| Profiles | Saved plugin sets (the TUI's own, older profile concept) |
+| CLI Tools | Install claudish, mnemex and friends via the right package manager |
+| Git State | Gitignore conventions and repo hygiene |
+| Alias | Shell alias + flag management for launching `claude` |
 
-Releases are automated via GitHub Actions using [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/) with OIDC - no tokens required.
+Navigate with `↑/↓` or `j/k`, `Enter` to select, `r` to refresh, `?` for help,
+`q`/`Escape` to go back. Number keys `1`–`8` jump straight to a screen.
 
-### One-Time Setup
+## Files claudeup touches
 
-1. **Publish first version manually** (required for new packages):
-   ```bash
-   npm run build
-   npm publish --access public
-   ```
+| Path | Owner | What claudeup does |
+|---|---|---|
+| `.claude/profiles.json` | you, committed | reads it; `profile sync` writes to it |
+| `.claude/_profiles/<name>/` | claudeup, gitignored | generated build output |
+| `.claude/settings.json` | Claude Code | in profile mode, a symlink into `_profiles/` |
+| `.claude/settings.local.json` | you, gitignored | env values collected during install |
+| `.mcp.json` | Claude Code | in profile mode, a symlink into `_profiles/` |
+| `~/.claude/plugins/*` | Claude Code | never written directly — always via the `claude` CLI |
 
-2. **Configure Trusted Publisher on npmjs.com** (already done):
-   - Repository: `MadAppGang/magus`
-   - Workflow: `claudeup-release.yml`
+claudeup never hand-edits Claude Code's own registries
+(`installed_plugins.json`, `known_marketplaces.json`, the plugin cache). Those go
+through `claude plugin ...` so Claude Code stays the single writer.
 
-### Releasing New Versions
+## Development
 
 ```bash
-# 1. Update version in package.json
-npm version patch  # or minor, major
-
-# 2. Push the tag
-git push origin main --tags
+bun install
+bun test                # full suite
+bun run typecheck
+bun run lint
+bun run src/main.tsx    # run from source
+bun run build:binaries  # cross-compile all platform binaries + their packages
 ```
 
-This triggers:
-1. **claudeup-release.yml** - Builds and publishes to npm via OIDC (no tokens needed)
-2. **create-release.yml** - Creates a GitHub release with changelog
+Tests run per-file isolated in CI (`bun run test:ci`) because `mock.module`
+leaks across files in a shared process.
+
+**Do not bump `@opentui` past 0.1.x.** 0.4.x breaks `bun build --compile`: it
+resolves tree-sitter workers eagerly, bypassing the `OTUI_ASSET_ROOT` override,
+so a bare `import "@opentui/core"` crashes at import time in the compiled
+binary. Re-run the compile spike before changing that pin.
 
-### Manual Release
+## Releasing
+
+Tag-driven. `.github/workflows/claudeup-release.yml` fires on `tools/claudeup/v*`:
+
+1. **verify** — install, typecheck, `test:ci`, version and optional-deps gates
+2. **binaries** — a matrix building each target on its **native** runner
+   (`bun --compile` cannot cross-compile in CI because opentui ships a
+   per-platform native library)
+3. **publish** — platform packages first, main package last, so its
+   `optionalDependencies` already resolve
 
 ```bash
-npm run build
-npm publish --access public
+# bump "version" AND the three optionalDependencies to match
+bun run check:optional-deps
+git commit -am "feat(claudeup): vX.Y.Z - description"
+git tag -a tools/claudeup/vX.Y.Z -m "Release message"
+git push origin main --tags
 ```
 
+Auth is npm OIDC trusted publishing — the workflow references no secrets. Adding
+a **new** platform target needs a one-time manual publish to create the package
+name (OIDC can only authenticate against a package that already exists); see
+[`docs/npm-trusted-publishing-setup.md`](../../docs/npm-trusted-publishing-setup.md).
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeup",
-  "version": "4.30.0",
+  "version": "4.32.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.30.0",
-    "claudeup-darwin-x64": "4.30.0",
-    "claudeup-linux-x64": "4.30.0"
+    "claudeup-darwin-arm64": "4.32.0",
+    "claudeup-darwin-x64": "4.32.0",
+    "claudeup-linux-x64": "4.32.0"
   }
 }

package/src/__tests__/content-drift.test.ts

@@ -0,0 +1,152 @@
+/**
+ * Content drift: a plugin whose files changed without its version changing.
+ *
+ * Hermetic — builds a real git marketplace under a temp CLAUDE_CONFIG_DIR.
+ * Real git is used deliberately: the detection IS a git question, and mocking
+ * it would only test the mock.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+	clearContentDriftCache,
+	hasContentDrift,
+} from "../services/content-drift.js";
+
+let configDir: string;
+let prevConfigDir: string | undefined;
+let repo: string;
+
+const git = (args: string[]) =>
+	spawnSync("git", args, { cwd: repo, encoding: "utf-8" });
+
+const head = () => git(["rev-parse", "HEAD"]).stdout.trim();
+
+beforeEach(async () => {
+	prevConfigDir = process.env.CLAUDE_CONFIG_DIR;
+	configDir = await fs.mkdtemp(path.join(os.tmpdir(), "drift-"));
+	process.env.CLAUDE_CONFIG_DIR = configDir;
+	clearContentDriftCache();
+
+	repo = path.join(configDir, "plugins", "marketplaces", "probemp");
+	await fs.mkdir(path.join(repo, "plugins", "alpha", "skills"), {
+		recursive: true,
+	});
+	await fs.mkdir(path.join(repo, "plugins", "beta"), { recursive: true });
+	await fs.writeFile(path.join(repo, "plugins", "alpha", "skills", "s.md"), "v1");
+	await fs.writeFile(path.join(repo, "plugins", "beta", "readme.md"), "v1");
+
+	git(["init", "-q", "-b", "main"]);
+	git(["config", "user.email", "probe@example.invalid"]);
+	git(["config", "user.name", "probe"]);
+	git(["add", "-A"]);
+	git(["commit", "-q", "-m", "release 1.0.0"]);
+});
+
+afterEach(async () => {
+	if (prevConfigDir === undefined) delete process.env.CLAUDE_CONFIG_DIR;
+	else process.env.CLAUDE_CONFIG_DIR = prevConfigDir;
+	await fs.rm(configDir, { recursive: true, force: true });
+});
+
+describe("hasContentDrift", () => {
+	test("no drift when the plugin's files are untouched", async () => {
+		const sha = head();
+		expect(
+			await hasContentDrift({
+				marketplace: "probemp",
+				pluginName: "alpha",
+				installedSha: sha,
+			}),
+		).toBe(false);
+	});
+
+	test("drift when the plugin's files change under an unchanged version", async () => {
+		const sha = head();
+		// Republish: same version, different content — what publish-dist.sh does.
+		await fs.writeFile(
+			path.join(repo, "plugins", "alpha", "skills", "s.md"),
+			"v2 — different content, same version",
+		);
+		git(["add", "-A"]);
+		git(["commit", "-q", "-m", "republish 1.0.0"]);
+
+		expect(
+			await hasContentDrift({
+				marketplace: "probemp",
+				pluginName: "alpha",
+				installedSha: sha,
+			}),
+		).toBe(true);
+	});
+
+	test("a change to ANOTHER plugin does not flag this one", async () => {
+		// The reason this compares the plugin subtree and not the marketplace
+		// HEAD: any commit to any plugin would otherwise flag every plugin.
+		const sha = head();
+		await fs.writeFile(path.join(repo, "plugins", "beta", "readme.md"), "v2");
+		git(["add", "-A"]);
+		git(["commit", "-q", "-m", "unrelated change"]);
+
+		expect(
+			await hasContentDrift({
+				marketplace: "probemp",
+				pluginName: "alpha",
+				installedSha: sha,
+			}),
+		).toBe(false);
+		expect(
+			await hasContentDrift({
+				marketplace: "probemp",
+				pluginName: "beta",
+				installedSha: sha,
+			}),
+		).toBe(true);
+	});
+
+	test("deleting a skill counts as drift", async () => {
+		// The live case: dev@magus 3.0.1 lost tui-progress/SKILL.md while still
+		// declaring 3.0.1, so the version compare reported "up to date".
+		const sha = head();
+		await fs.rm(path.join(repo, "plugins", "alpha", "skills", "s.md"));
+		git(["add", "-A"]);
+		git(["commit", "-q", "-m", "drop a skill"]);
+
+		expect(
+			await hasContentDrift({
+				marketplace: "probemp",
+				pluginName: "alpha",
+				installedSha: sha,
+			}),
+		).toBe(true);
+	});
+
+	test("stays silent when it cannot answer honestly", async () => {
+		// No recorded sha, unknown sha (force-push/shallow clone), and unknown
+		// marketplace must all report false rather than nag for a reinstall.
+		expect(
+			await hasContentDrift({
+				marketplace: "probemp",
+				pluginName: "alpha",
+				installedSha: undefined,
+			}),
+		).toBe(false);
+		expect(
+			await hasContentDrift({
+				marketplace: "probemp",
+				pluginName: "alpha",
+				installedSha: "0".repeat(40),
+			}),
+		).toBe(false);
+		expect(
+			await hasContentDrift({
+				marketplace: "does-not-exist",
+				pluginName: "alpha",
+				installedSha: head(),
+			}),
+		).toBe(false);
+	});
+});

package/src/__tests__/dual-write-prevention.test.ts

@@ -94,7 +94,10 @@ describe("PluginsScreen — no dual-write after CLI operations", () => {
 
 // Mutable state shared between mock factories and test assertions.
 let mockSaveGlobal: ReturnType<typeof mock>;
+let mockSaveProject: ReturnType<typeof mock>;
+let mockSaveLocal: ReturnType<typeof mock>;
 let mockUpdatePlugin: ReturnType<typeof mock>;
+let mockRepairPlugin: ReturnType<typeof mock>;
 let mockIsClaudeAvailable: ReturnType<typeof mock>;
 let mockGetAvailablePlugins: ReturnType<typeof mock>;
 
@@ -123,6 +126,8 @@ mock.module("../services/claude-settings.js", () => ({
   getLocalEnabledPlugins: mock(() => Promise.resolve({})),
   saveGlobalInstalledPluginVersion: (...args: unknown[]) =>
     mockSaveGlobal(...args),
+  saveLocalInstalledPluginVersion: (...args: unknown[]) =>
+    mockSaveLocal(...args),
   readGlobalSettings: mock(() => Promise.resolve({ hooks: {} })),
   writeGlobalSettings: mock(() => Promise.resolve()),
 }));
@@ -130,6 +135,7 @@ mock.module("../services/claude-settings.js", () => ({
 mock.module("../services/claude-cli.js", () => ({
   ...actualClaudeCli,
   updatePlugin: (...args: unknown[]) => mockUpdatePlugin(...args),
+  repairPlugin: (...args: unknown[]) => mockRepairPlugin(...args),
   isClaudeAvailable: (...args: unknown[]) => mockIsClaudeAvailable(...args),
   addMarketplace: mock(() => Promise.resolve()),
   updateMarketplace: mock(() => Promise.resolve()),
@@ -139,6 +145,7 @@ mock.module("../services/plugin-manager.js", () => ({
   ...actualPluginManager,
   getAvailablePlugins: (...args: unknown[]) =>
     mockGetAvailablePlugins(...args),
+  saveInstalledPluginVersion: (...args: unknown[]) => mockSaveProject(...args),
   clearMarketplaceCache: mock(() => undefined),
 }));
 
@@ -173,26 +180,35 @@ mock.module("fs-extra", () => ({
 // Now import the module under test (after mock.module registrations).
 const { prerunClaude } = await import("../prerunner/index.js");
 
-// Helper: build a minimal PluginInfo-like object
-function makePlugin(overrides: Partial<{
-  id: string;
+interface ScopeStatusLike {
   enabled: boolean;
-  hasUpdate: boolean;
-  installedVersion: string;
-  version: string;
-}> = {}): {
+  version?: string;
+}
+interface PluginLike {
   id: string;
   enabled: boolean;
   hasUpdate: boolean;
+  contentStale?: boolean;
   installedVersion: string;
   version: string;
-} {
+  userScope?: ScopeStatusLike;
+  projectScope?: ScopeStatusLike;
+  localScope?: ScopeStatusLike;
+}
+
+/**
+ * Minimal PluginInfo-like object. The per-scope status matters: the prerunner
+ * updates the scopes that actually hold an outdated install, so a fixture with
+ * no scope status describes a plugin installed nowhere and is correctly skipped.
+ */
+function makePlugin(overrides: Partial<PluginLike> = {}): PluginLike {
   return {
     id: "test-plugin@magus",
     enabled: true,
     hasUpdate: true,
     installedVersion: "1.0.0",
     version: "1.1.0",
+    userScope: { enabled: true, version: "1.0.0" },
     ...overrides,
   };
 }
@@ -200,7 +216,10 @@ function makePlugin(overrides: Partial<{
 describe("prerunner — saveGlobalInstalledPluginVersion call count", () => {
   beforeEach(() => {
     mockSaveGlobal = mock(() => Promise.resolve());
+    mockSaveProject = mock(() => Promise.resolve());
+    mockSaveLocal = mock(() => Promise.resolve());
     mockUpdatePlugin = mock(() => Promise.resolve());
+    mockRepairPlugin = mock(() => Promise.resolve());
     mockIsClaudeAvailable = mock(() => Promise.resolve(true));
     mockGetAvailablePlugins = mock(() =>
       Promise.resolve([makePlugin()]),
@@ -219,6 +238,130 @@ describe("prerunner — saveGlobalInstalledPluginVersion call count", () => {
     expect(mockSaveGlobal).toHaveBeenCalledTimes(1);
   });
 
+  /**
+   * The prerunner used to call `updatePlugin(id, "user")` unconditionally.
+   * `hasUpdate` is computed from the CURRENT PROJECT's resolved version, but
+   * installs live per project in installed_plugins.json — 495 of 496 magus
+   * installs on the reporter's machine are project-scoped. So it detected
+   * project drift, updated user scope, reported success, and left the project
+   * untouched, re-detecting the identical drift on every subsequent run.
+   */
+  it("updates the PROJECT scope when that is where the outdated install is", async () => {
+    mockGetAvailablePlugins = mock(() =>
+      Promise.resolve([
+        makePlugin({
+          userScope: undefined,
+          projectScope: { enabled: true, version: "1.0.0" },
+        }),
+      ]),
+    );
+
+    await prerunClaude(["--help"], { force: true });
+
+    expect(mockUpdatePlugin).toHaveBeenCalledTimes(1);
+    expect(mockUpdatePlugin.mock.calls[0]?.[1]).toBe("project");
+    expect(mockSaveProject).toHaveBeenCalledTimes(1);
+    expect(mockSaveGlobal).toHaveBeenCalledTimes(0);
+  });
+
+  it("updates every scope that is outdated, not just the first", async () => {
+    mockGetAvailablePlugins = mock(() =>
+      Promise.resolve([
+        makePlugin({
+          userScope: { enabled: true, version: "1.0.0" },
+          projectScope: { enabled: true, version: "1.0.0" },
+          localScope: { enabled: true, version: "1.1.0" }, // already current
+        }),
+      ]),
+    );
+
+    await prerunClaude(["--help"], { force: true });
+
+    const scopes = mockUpdatePlugin.mock.calls
+      .map((c: unknown[]) => c[1])
+      .sort();
+    expect(scopes).toEqual(["project", "user"]);
+    expect(mockSaveLocal).toHaveBeenCalledTimes(0);
+  });
+
+  /**
+   * A content-stale plugin has no version bump to install over, and
+   * `claude plugin install` no-ops on "already installed" (verified against the
+   * real marketplace in autotest/plugin-system/probe-05). The prerunner must
+   * therefore repair — uninstall+install — not update.
+   */
+  it("repairs a content-stale plugin instead of updating it", async () => {
+    mockGetAvailablePlugins = mock(() =>
+      Promise.resolve([
+        makePlugin({
+          hasUpdate: false,
+          contentStale: true,
+          installedVersion: "1.0.0",
+          version: "1.0.0",
+          userScope: undefined,
+          projectScope: { enabled: true, version: "1.0.0" },
+        }),
+      ]),
+    );
+
+    await prerunClaude(["--help"], { force: true });
+
+    expect(mockRepairPlugin).toHaveBeenCalledTimes(1);
+    expect(mockRepairPlugin.mock.calls[0]?.[1]).toBe("project");
+    expect(mockUpdatePlugin).toHaveBeenCalledTimes(0);
+  });
+
+  it("prefers a real version update over a repair when both apply", async () => {
+    // A pending version bump reinstalls the files anyway, so repairing as well
+    // would double the work and the uninstall window.
+    mockGetAvailablePlugins = mock(() =>
+      Promise.resolve([
+        makePlugin({ hasUpdate: true, contentStale: true }),
+      ]),
+    );
+
+    await prerunClaude(["--help"], { force: true });
+
+    expect(mockUpdatePlugin).toHaveBeenCalledTimes(1);
+    expect(mockRepairPlugin).toHaveBeenCalledTimes(0);
+  });
+
+  it("does not repair when the CLI is unavailable", async () => {
+    mockIsClaudeAvailable = mock(() => Promise.resolve(false));
+    mockGetAvailablePlugins = mock(() =>
+      Promise.resolve([
+        makePlugin({
+          hasUpdate: false,
+          contentStale: true,
+          version: "1.0.0",
+          projectScope: { enabled: true, version: "1.0.0" },
+        }),
+      ]),
+    );
+
+    await prerunClaude(["--help"], { force: true });
+
+    expect(mockRepairPlugin).toHaveBeenCalledTimes(0);
+  });
+
+  it("does nothing when no scope holds an outdated install", async () => {
+    // hasUpdate can be true from a stale settings base while every real
+    // install is already current. Updating "somewhere" would be a guess.
+    mockGetAvailablePlugins = mock(() =>
+      Promise.resolve([
+        makePlugin({
+          userScope: { enabled: true, version: "1.1.0" },
+          projectScope: undefined,
+        }),
+      ]),
+    );
+
+    await prerunClaude(["--help"], { force: true });
+
+    expect(mockUpdatePlugin).toHaveBeenCalledTimes(0);
+    expect(mockSaveGlobal).toHaveBeenCalledTimes(0);
+  });
+
   it("does NOT call saveGlobalInstalledPluginVersion when CLI is unavailable", async () => {
     // CLI unavailable — we must NOT write phantom state.
     mockIsClaudeAvailable = mock(() => Promise.resolve(false));

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

@@ -214,14 +214,19 @@ describe("refreshRegisteredMarketplaces — selection & skips", () => {
 		expect(r.skipped).toEqual(["local"]);
 	});
 
-	it("skips a marketplace with autoUpdate === false", async () => {
+	it("reports a marketplace with autoUpdate === false separately from ordinary skips", async () => {
+		// Not lumped into `skipped`: opting out here freezes the catalog, so the
+		// marketplace's plugins read as up to date forever. The caller has to be
+		// able to tell the user, which it cannot do if this looks like "no clone
+		// on disk". A real magus clone sat 11 days behind exactly this way.
 		installClone("magus");
 		publishV2();
 		configured = { magus: gh() };
 		autoUpdate = { magus: false };
 		const r = await refreshRegisteredMarketplaces();
 		expect(r.refreshed).toEqual([]);
-		expect(r.skipped).toEqual(["magus"]);
+		expect(r.autoUpdateDisabled).toEqual(["magus"]);
+		expect(r.skipped).toEqual([]);
 	});
 
 	it("honors the skip set (already handled this run)", async () => {