claudeup 4.29.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.29.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.29.0",
-    "claudeup-darwin-x64": "4.29.0",
-    "claudeup-linux-x64": "4.29.0"
+    "claudeup-darwin-arm64": "4.31.0",
+    "claudeup-darwin-x64": "4.31.0",
+    "claudeup-linux-x64": "4.31.0"
   }
 }