claudeup 4.30.0 → 4.31.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.31.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.31.0",
+    "claudeup-darwin-x64": "4.31.0",
+    "claudeup-linux-x64": "4.31.0"
   }
 }

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

@@ -38,6 +38,36 @@ describe("buildProfileSettings", () => {
 		});
 		expect(s.enableAllProjectMcpServers).toBe(true);
 	});
+
+	// Regression: `install` enables the manifest-wide union at USER scope, and
+	// Claude Code resolves enabledPlugins per plugin id — an id the project
+	// scope omits falls through to the user scope's `true`. A profile that
+	// merely omits another profile's plugins therefore never disables them, so
+	// `profile switch` silently becomes additive instead of exclusive.
+	test("explicitly disables union plugins the profile excludes", () => {
+		const s = buildProfileSettings(
+			closure({ plugins: { "designer@magus": "latest" } }),
+			["designer@magus", "terminal@magus", "gtd@magus"],
+		);
+		expect(s.enabledPlugins).toEqual({
+			"designer@magus": true,
+			"terminal@magus": false,
+			"gtd@magus": false,
+		});
+	});
+
+	test("a profile's own plugin wins over its union entry", () => {
+		const s = buildProfileSettings(
+			closure({ plugins: { "terminal@magus": "4.1.4" } }),
+			["terminal@magus"],
+		);
+		expect(s.enabledPlugins).toEqual({ "terminal@magus": true });
+	});
+
+	test("no union given -> no false entries (unchanged legacy shape)", () => {
+		const s = buildProfileSettings(closure({ plugins: { "dev@magus": "latest" } }));
+		expect(s.enabledPlugins).toEqual({ "dev@magus": true });
+	});
 });
 
 describe("buildProfileMcp", () => {
@@ -79,4 +109,61 @@ describe("materializeProfile", () => {
 		const settings = await fs.readJson(join(dir, "settings.json"));
 		expect(settings.enabledPlugins).toEqual({ "b@m": true });
 	});
+
+	// Regression: activating a profile replaces .claude/skills with a symlink,
+	// and replacing means fs.remove first. A repo that committed its own project
+	// skills before adopting profiles would lose them at that moment.
+	test("seeds skills/ from the project's pre-existing .claude/skills", async () => {
+		const src = join(project, ".claude", "skills", "systematic-debugging");
+		await fs.outputFile(join(src, "SKILL.md"), "# committed project skill\n");
+
+		const dir = await materializeProfile("p", closure(), project);
+
+		expect(
+			await fs.readFile(join(dir, "skills", "systematic-debugging", "SKILL.md"), "utf8"),
+		).toContain("committed project skill");
+	});
+
+	test("does not re-seed skills/ once the profile dir exists", async () => {
+		await fs.outputFile(
+			join(project, ".claude", "skills", "gone", "SKILL.md"),
+			"# removed later\n",
+		);
+		const dir = await materializeProfile("p", closure(), project);
+		await fs.remove(join(dir, "skills", "gone"));
+
+		await materializeProfile("p", closure(), project);
+
+		expect(await fs.pathExists(join(dir, "skills", "gone"))).toBe(false);
+	});
+
+	test("still creates an empty skills/ when the project has none", async () => {
+		const dir = await materializeProfile("p", closure(), project);
+		expect(await fs.pathExists(join(dir, "skills"))).toBe(true);
+		expect(await fs.readdir(join(dir, "skills"))).toEqual([]);
+	});
+
+	test("two profiles from one union each disable the other's plugins", async () => {
+		const union = ["designer@magus", "terminal@magus"];
+		const fe = await materializeProfile(
+			"frontend",
+			closure({ plugins: { "designer@magus": "latest" } }),
+			project,
+			union,
+		);
+		const be = await materializeProfile(
+			"backend",
+			closure({ plugins: { "terminal@magus": "latest" } }),
+			project,
+			union,
+		);
+		expect((await fs.readJson(join(fe, "settings.json"))).enabledPlugins).toEqual({
+			"designer@magus": true,
+			"terminal@magus": false,
+		});
+		expect((await fs.readJson(join(be, "settings.json"))).enabledPlugins).toEqual({
+			"designer@magus": false,
+			"terminal@magus": true,
+		});
+	});
 });

package/src/cli/install.ts

@@ -126,7 +126,16 @@ async function runCheck(
 // ── install steps ───────────────────────────────────────────────────────────
 
 async function ensureToolchains(closure: ResolvedClosure, yes: boolean): Promise<void> {
-	const toolchains = await detectToolchains(closure.bins);
+	// Only the binaries actually missing can need a toolchain. Checking all of
+	// them warns "pip isn't installed" on a machine whose pip-provided binaries
+	// are already on PATH — an alarming message about work that will not happen.
+	const missing: ResolvedBin[] = [];
+	for (const bin of closure.bins) {
+		if (!(await resolveExecutable(bin.name))) missing.push(bin);
+	}
+	if (missing.length === 0) return;
+
+	const toolchains = await detectToolchains(missing);
 	for (const tc of toolchains) {
 		if (tc.present) continue;
 		const bootstrap = TOOLCHAIN_BOOTSTRAP[tc.name];
@@ -160,11 +169,25 @@ async function registerMarketplaces(closure: ResolvedClosure): Promise<void> {
 	}
 }
 
+/**
+ * Install the closure's plugins at PROJECT scope.
+ *
+ * A profile is a property of one repo, so its plugins must be too. At user
+ * scope, adopting profiles in a single repo would enable that repo's plugins in
+ * every other project on the machine — and since Claude Code resolves
+ * enabledPlugins per id with fall-through, those would stay on everywhere.
+ * Project scope keeps the blast radius to this repo. The plugin *cache* is
+ * global either way, so `profile switch` stays offline.
+ *
+ * Whatever the CLI writes into .claude/settings.json here is transient:
+ * materialization rewrites that file from the manifest, and activation replaces
+ * it with a symlink. The manifest stays authoritative.
+ */
 async function installPlugins(closure: ResolvedClosure): Promise<void> {
 	for (const pluginId of Object.keys(closure.plugins)) {
 		try {
 			console.log(`+ plugin ${pluginId}`);
-			await installPlugin(pluginId, "user");
+			await installPlugin(pluginId, "project");
 		} catch (e) {
 			console.warn(`⚠ plugin ${pluginId}: ${(e as Error).message}`);
 		}
@@ -317,10 +340,18 @@ export async function runInstallCommand(
 
 	// Materialize every profile (so `profile switch` needs no reinstall), then
 	// activate the target (or the sole/first profile).
-	const toMaterialize = flags.profile ? [flags.profile] : profileIds;
-	for (const id of toMaterialize) {
+	//
+	// Every profile is materialized even when one was named: a profile arg scopes
+	// what gets *installed* and which becomes active, not which settings files
+	// exist. It also keeps the union below consistent across all of them — a
+	// profile left holding an older union would stop disabling plugins added
+	// since, silently making `switch` additive again.
+	const unionPluginIds = Object.keys(
+		(flags.profile ? await resolveAllProfiles(manifest) : closure).plugins,
+	);
+	for (const id of profileIds) {
 		const profileClosure = await resolveProfile(manifest, id);
-		await materializeProfile(id, profileClosure, projectPath);
+		await materializeProfile(id, profileClosure, projectPath, unionPluginIds);
 	}
 
 	// Keep the generated dir + active-profile symlinks out of git before

package/src/cli/router.ts

@@ -73,25 +73,33 @@ function printHelp(version: string): void {
 
 TUI tool for managing Claude Code plugins, MCPs, and configuration.
 
-Usage: claudeup [options]
-       claudeup claude [args...]  Run claude with auto-update prerunner
-       claudeup update            Update claudeup to latest version
+Usage: claudeup                    Open the interactive TUI
+       claudeup <command> [args]
 
 Options:
   -v, --version  Show version and check for updates
   -h, --help     Show this help message
   --no-refresh   Skip auto-refresh of marketplaces on startup
 
-Commands:
+Team profiles — reproduce this repo's Claude Code setup on any machine.
+The manifest is .claude/profiles.json, committed. See docs/team-configuration.md.
+  install [profile]  Install the profile's plugins, binaries, skills and env,
+                     then activate it. No argument installs every profile.
+    --check          Report drift only, write nothing (exits 1 in strict mode)
+    --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 <n>   Print a profile's fully resolved closure
+  profile switch <n> Repoint the active profile — offline, no reinstall
+  profile sync       Promote local edits back into .claude/profiles.json
+  doctor             Check binary deps, profile symlinks, and conventions
+    --fix            Apply the repairs it can make itself
+
+Other commands:
   claude [args...]   Check for plugin updates (1h cache), then run claude
     -f, --force      Force update check (bypass 1h cache)
   update             Update claudeup itself to latest version
 
-Experimental (in development):
-  install [profile]  Install a team profile from .claude/profiles.json
-  profile <cmd>      list | show | switch | sync team profiles
-  doctor             Diagnose & repair plugin/marketplace/profile state
-
 Navigation (TUI):
   [1] Plugins    [4] Settings   [7] Git State
   [2] Skills     [5] Profiles   [8] Alias

package/src/services/profile-materializer.ts

@@ -21,11 +21,26 @@ import { profileDir } from "./symlink-manager.js";
  * enabled, merged with the profile's declared settings. The profile's settings
  * win over the derived enabledPlugins only if it explicitly sets that key
  * (it normally won't).
+ *
+ * `allPluginIds` is the manifest-wide union of plugins across every profile.
+ * Plugins in the union that this profile does NOT want are written as an
+ * explicit `false`, which is what makes `profile switch` exclusive rather than
+ * additive. Claude Code resolves enabledPlugins **per plugin id**, walking from
+ * the highest-precedence scope down and taking the first scope that mentions
+ * the id — an id a scope omits falls through to the next one. Since
+ * `claudeup install` installs the union at user scope, every non-member would
+ * otherwise inherit that user-scope `true` and stay enabled while a profile
+ * that excludes it is active. Omitting the union (the default) preserves the
+ * old additive behavior for callers that have no cross-profile view.
  */
 export function buildProfileSettings(
 	closure: ResolvedClosure,
+	allPluginIds: readonly string[] = [],
 ): Record<string, unknown> {
 	const enabledPlugins: Record<string, boolean> = {};
+	for (const pluginId of allPluginIds) {
+		enabledPlugins[pluginId] = false;
+	}
 	for (const pluginId of Object.keys(closure.plugins)) {
 		enabledPlugins[pluginId] = true;
 	}
@@ -39,6 +54,37 @@ export function buildProfileMcp(
 	return { mcpServers: { ...closure.mcpServers } };
 }
 
+/**
+ * Seed a profile's skills/ dir from the project's pre-existing `.claude/skills/`.
+ *
+ * Activating a profile replaces `.claude/skills` with a symlink into the profile
+ * dir, and replacing means `fs.remove` first. A project that committed its own
+ * skills before adopting profiles would lose them at that moment. So the first
+ * time a profile's skills/ dir is created, any real (non-symlink) project skills
+ * are copied in — every profile inherits what the project already had, and the
+ * link swap destroys nothing.
+ *
+ * Only runs when the profile's skills/ dir does not exist yet, so it never
+ * fights a later `skills-manager` install or re-adds a skill the user removed.
+ */
+async function seedSkillsFromProject(
+	skillsDir: string,
+	projectPath?: string,
+): Promise<void> {
+	if (await fs.pathExists(skillsDir)) return;
+
+	const projectSkills = path.join(projectPath ?? process.cwd(), ".claude", "skills");
+	try {
+		// lstat, not pathExists: an existing profile symlink is not a source.
+		const stat = await fs.lstat(projectSkills);
+		if (!stat.isDirectory() || stat.isSymbolicLink()) return;
+		if ((await fs.readdir(projectSkills)).length === 0) return;
+		await fs.copy(projectSkills, skillsDir, { dereference: true });
+	} catch {
+		// No project skills dir (or unreadable) — nothing to carry over.
+	}
+}
+
 /**
  * Write `_profiles/<name>/` from a resolved closure. Idempotent: overwrites
  * settings.json / mcp.json and ensures skills/ exists. Returns the dir path.
@@ -47,15 +93,20 @@ export async function materializeProfile(
 	name: string,
 	closure: ResolvedClosure,
 	projectPath?: string,
+	allPluginIds: readonly string[] = [],
 ): Promise<string> {
 	const dir = profileDir(name, projectPath);
 	await fs.ensureDir(dir);
-	await fs.writeJson(path.join(dir, "settings.json"), buildProfileSettings(closure), {
-		spaces: 2,
-	});
+	await fs.writeJson(
+		path.join(dir, "settings.json"),
+		buildProfileSettings(closure, allPluginIds),
+		{ spaces: 2 },
+	);
 	await fs.writeJson(path.join(dir, "mcp.json"), buildProfileMcp(closure), {
 		spaces: 2,
 	});
-	await fs.ensureDir(path.join(dir, "skills"));
+	const skillsDir = path.join(dir, "skills");
+	await seedSkillsFromProject(skillsDir, projectPath);
+	await fs.ensureDir(skillsDir);
 	return dir;
 }