@learnrudi/cli 1.9.7 → 1.9.9

package/README.md

@@ -1,6 +1,6 @@
 # RUDI CLI
 
-Install and manage MCP stacks, runtimes, and AI agents.
+Universal tool manager for MCP stacks, CLI tools, runtimes, and AI agents.
 
 ## Install
 
@@ -8,91 +8,163 @@ Install and manage MCP stacks, runtimes, and AI agents.
 npm i -g @learnrudi/cli
 ```
 
-Requires Node.js + npm. The npm postinstall step bootstraps `~/.rudi` and
-downloads the default runtimes.
+Requires Node.js 18+. The postinstall step bootstraps `~/.rudi` and creates shims.
 
-## Installation Flow (CLI + Studio)
+## Quick Start
 
-### CLI (npm)
+```bash
+# Install any npm CLI tool
+rudi install npm:typescript
+rudi install npm:@stripe/cli
+rudi install npm:vercel
 
-1. `npm i -g @learnrudi/cli` downloads the CLI package.
-2. Postinstall creates `~/.rudi/` folders, downloads Node/Python runtimes,
-   creates `~/.rudi/shims/rudi-mcp`, and initializes `~/.rudi/secrets.json`.
-3. Run `rudi init` to create `~/.rudi/rudi.db`, write `settings.json`, and
-   ensure essential binaries and shims are present.
+# Install curated stacks and tools
+rudi install slack
+rudi install binary:ffmpeg
+rudi install binary:supabase
 
-### Studio (desktop app)
+# All tools available via ~/.rudi/bins/
+tsc --version
+ffmpeg -version
+supabase --version
 
-1. Studio bundles the CLI and installs it to `~/.rudi/bins/rudi`.
-2. On first launch, Studio runs `rudi init` unless `~/.rudi` is already
-   initialized.
-3. CLI and Studio share the same `~/.rudi` home, so stacks, runtimes, secrets,
-   and the database stay in sync.
+# Configure secrets for stacks
+rudi secrets set SLACK_BOT_TOKEN "xoxb-your-token"
 
-If you already use Studio, you can skip the npm install unless you want the
-`rudi` command in your shell. If you already use the CLI, Studio will reuse the
-existing `~/.rudi` setup.
+# Wire up your AI agents
+rudi integrate all
+```
 
-## Quick Start
+## Features
+
+### Universal Tool Installation
+
+RUDI supports multiple installation paths:
 
 ```bash
-# Search available stacks
-rudi search --all
+# Dynamic npm packages (any npm CLI)
+rudi install npm:cowsay
+rudi install npm:typescript
+rudi install npm:@railway/cli
 
-# Install a stack
-rudi install slack
+# Curated registry (stacks and binaries with docs)
+rudi install slack              # MCP stack
+rudi install binary:ffmpeg      # Upstream binary
+rudi install binary:supabase    # npm-based CLI
 
-# Configure secrets
-rudi secrets set SLACK_BOT_TOKEN "xoxb-your-token"
+# All tools resolve through ~/.rudi/bins/
+```
 
-# Wire up your agents (Claude, Gemini, VS Code, etc.)
-rudi integrate all
+### Shim-First Architecture
+
+Every installed tool gets a shim in `~/.rudi/bins/`:
+
+```bash
+# Add to your shell profile (.bashrc, .zshrc)
+export PATH="$HOME/.rudi/bins:$PATH"
+
+# Then use tools directly
+tsc --version      # → ~/.rudi/bins/tsc
+ffmpeg -version    # → ~/.rudi/bins/ffmpeg
+supabase --help    # → ~/.rudi/bins/supabase
+```
+
+### Security by Default
+
+npm packages run with `--ignore-scripts` by default:
+
+```bash
+# Safe install (scripts skipped)
+rudi install npm:some-package
 
-# Restart your agent to use the new stack
+# If CLI fails, opt-in to scripts
+rudi install npm:some-package --allow-scripts
 ```
 
 ## Commands
 
 ```bash
-rudi search <query>       # Search for packages
-rudi search --all         # List all packages
-rudi install <pkg>        # Install a package
-rudi remove <pkg>         # Remove a package
-rudi list [kind]          # List installed (stacks, runtimes, binaries, agents)
-rudi secrets list         # Show configured secrets
-rudi secrets set <key>    # Set a secret
-rudi integrate <agent>    # Wire stack to agent config
-rudi update [pkg]         # Update packages
-rudi doctor               # Check system health
+# Search and install
+rudi search <query>         # Search for packages
+rudi search --all           # List all packages
+rudi install <pkg>          # Install a package
+rudi install npm:<pkg>      # Install any npm CLI
+rudi remove <pkg>           # Remove a package
+
+# List and inspect
+rudi list [kind]            # List installed (stacks, binaries, agents)
+rudi pkg <id>               # Show package details and shim status
+rudi shims list             # List all shims
+rudi shims check            # Validate shim targets
+
+# Secrets and integration
+rudi secrets list           # Show configured secrets
+rudi secrets set <key>      # Set a secret
+rudi integrate <agent>      # Wire stack to agent config
+
+# Maintenance
+rudi update [pkg]           # Update packages
+rudi doctor                 # Check system health
 ```
 
 ## How It Works
 
-1. `rudi install slack` downloads the MCP server tarball from GitHub releases
+### Installing a Package
+
+```bash
+rudi install npm:typescript
+```
+
+1. Resolves package from npm registry
+2. Creates install directory at `~/.rudi/binaries/npm/typescript/`
+3. Runs `npm install typescript --ignore-scripts`
+4. Discovers binaries from package.json (`tsc`, `tsserver`)
+5. Creates wrapper shims in `~/.rudi/bins/`
+6. Records ownership in shim registry
+
+### Installing an MCP Stack
+
+```bash
+rudi install slack
+```
+
+1. Downloads stack tarball from registry
 2. Extracts to `~/.rudi/stacks/slack/`
-3. Runs `npm install` to install dependencies
-4. Shows which secrets need to be configured
+3. Runs `npm install` for dependencies
+4. Shows which secrets need configuration
+5. Ready for `rudi integrate` to wire to agents
 
-When an agent runs the stack:
-1. Agent config points to `~/.rudi/shims/rudi-mcp`
-2. Shim calls `rudi mcp slack`
-3. RUDI loads secrets from `~/.rudi/secrets.json`
-4. Injects secrets as environment variables
-5. Runs the MCP server with bundled runtime
+### Running MCP Stacks
+
+When an AI agent runs a stack:
+
+1. Agent config points to `~/.rudi/bins/rudi-mcp`
+2. RUDI loads secrets from `~/.rudi/secrets.json`
+3. Injects secrets as environment variables
+4. Runs the MCP server with bundled runtime
 
 ## Directory Structure
 
 ```
 ~/.rudi/
+├── bins/             # Shims for all tools (add to PATH)
 ├── stacks/           # Installed MCP stacks
+├── binaries/         # Installed CLI tools
+│   ├── ffmpeg/       # Upstream binary
+│   ├── supabase/     # npm-based CLI
+│   └── npm/          # Dynamic npm packages
+│       ├── typescript/
+│       └── cowsay/
 ├── runtimes/         # Bundled Node.js, Python
-├── tools/            # Binaries (ffmpeg, ripgrep, etc.)
-├── shims/            # Shim scripts for agent configs
-├── secrets.json      # Encrypted secrets (0600 permissions)
+├── agents/           # AI agent CLIs
+├── secrets.json      # Encrypted secrets
+├── shim-registry.json # Shim ownership tracking
 └── rudi.db           # Local database
 ```
 
-## Available Stacks
+## Available Packages
+
+### MCP Stacks
 
 | Stack | Description |
 |-------|-------------|
@@ -103,10 +175,30 @@ When an agent runs the stack:
 | openai | DALL-E, Whisper, TTS, Sora |
 | postgres | PostgreSQL database queries |
 | video-editor | ffmpeg-based video editing |
-| content-extractor | YouTube, Reddit, TikTok, articles |
 | github | Issues, PRs, repos, actions |
 | stripe | Payments, subscriptions, invoices |
 
+### Binaries
+
+| Binary | Description |
+|--------|-------------|
+| ffmpeg | Video/audio processing |
+| ripgrep | Fast search |
+| supabase | Supabase CLI |
+| vercel | Vercel CLI |
+| uv | Fast Python package manager |
+
+### Dynamic npm
+
+Any npm package with a `bin` field works:
+
+```bash
+rudi install npm:typescript    # tsc, tsserver
+rudi install npm:cowsay        # cowsay, cowthink
+rudi install npm:@stripe/cli   # stripe
+rudi install npm:netlify-cli   # netlify
+```
+
 ## Links
 
 - Website: https://learnrudi.com