nushell-plugins/guides/UPDATE_INSTALLED_PLUGINS_GUIDE.md

# Update Installed Plugins Guide

## Overview

The `scripts/update_installed_plugins.nu` script manages updating Nushell plugins that are already installed in `~/.local/bin`. It:

1. **Detects** which plugins are installed
2. **Matches** them with source code in the repository
3. **Removes** old plugin binaries
4. **Rebuilds** plugins from source
5. **Installs** new versions to `~/.local/bin`
6. **Registers** plugins with Nushell

This is different from `update_all_plugins.nu` which only updates Cargo.toml dependencies.

## Quick Start

### Update All Installed Plugins

```bash
# Check what would be updated (dry-run)
./scripts/update_installed_plugins.nu --check

# Update all installed plugins (with confirmation)
./scripts/update_installed_plugins.nu

# Update with verification
./scripts/update_installed_plugins.nu --verify

# Force rebuild (ignore cache)
./scripts/update_installed_plugins.nu --force
```

### Update Specific Plugin

```bash
# Check if plugin can be updated
./scripts/update_installed_plugins.nu --plugin nu_plugin_auth --check

# Update specific plugin
./scripts/update_installed_plugins.nu --plugin nu_plugin_auth

# Update specific plugin without registering
./scripts/update_installed_plugins.nu --plugin nu_plugin_auth --no-register
```

## Full Command Reference

### Basic Options

| Option | Short | Purpose | Default |
|--------|-------|---------|---------|
| `--check` | `-c` | Dry-run mode, no actual changes | `false` |
| `--verify` | `-v` | Verify registration after update | `false` |
| `--force` | `-f` | Force rebuild (clean build artifacts) | `false` |
| `--plugin NAME` | - | Update only specific plugin | All installed |
| `--no-register` | - | Skip registration step | `false` |

### Examples

```bash
# 1. Dry-run to see what would happen
./scripts/update_installed_plugins.nu --check

# 2. Update all plugins with verification
./scripts/update_installed_plugins.nu --verify

# 3. Update with force rebuild and verification
./scripts/update_installed_plugins.nu --force --verify

# 4. Update specific plugin
./scripts/update_installed_plugins.nu --plugin nu_plugin_kms

# 5. Check specific plugin only
./scripts/update_installed_plugins.nu --plugin nu_plugin_orchestrator --check

# 6. Update and skip registration (register manually later)
./scripts/update_installed_plugins.nu --no-register
```

## What This Script Does

### Step 1: Detection
```
📋 Step 1: Detecting installed plugins...
Found 3 installed plugin(s):
  • nu_plugin_auth (installed: /Users/user/.local/bin/nu_plugin_auth)
  • nu_plugin_kms (installed: /Users/user/.local/bin/nu_plugin_kms)
  • nu_plugin_orchestrator (installed: /Users/user/.local/bin/nu_plugin_orchestrator)
```

Scans `~/.local/bin` for executables matching `nu_plugin_*` pattern.

### Step 2: Source Discovery
```
🔍 Step 2: Finding plugin sources...
Found 5 plugin source(s)
```

Finds all `nu_plugin_*` directories in the current repository.

### Step 3: Matching
```
🔗 Step 3: Matching installed plugins with sources...
Ready to update 3 plugin(s):
  • nu_plugin_auth
    Source: /path/to/nu_plugin_auth
    Target: ~/.local/bin/nu_plugin_auth
```

Matches installed plugins with their source directories.

### Step 4: Removal
```
🗑️  Step 4: Removing old plugin binaries...
  Removing: nu_plugin_auth
    ✓ Deleted
```

Removes old plugin binaries from `~/.local/bin`.

### Step 5: Building
```
🔨 Step 5: Building updated plugins...
  Building: nu_plugin_auth
    Cleaning build artifacts...
    Compiling...
    ✓ Built successfully
```

Rebuilds plugins with `cargo build --release` (optional cleanup with `--force`).

### Step 6: Installation
```
📦 Step 6: Installing new plugin binaries...
  Installing: nu_plugin_auth
    ✓ Installed to ~/.local/bin/nu_plugin_auth
```

Copies new binaries to `~/.local/bin` with execute permission.

### Step 7: Registration
```
🔌 Step 7: Registering plugins with nushell...
  Registering: nu_plugin_auth
    ✓ Registered
    ✓ Verified
```

Registers plugins with Nushell (removes old registration first).

## Workflow Examples

### Complete Update Cycle

```bash
# 1. Check what would be updated
./scripts/update_installed_plugins.nu --check

# 2. Update all plugins
./scripts/update_installed_plugins.nu

# 3. Restart shell to load new plugins
exit

# 4. Verify plugins are working
nu -c "plugin list"
nu -c "auth login --help"  # Test a specific plugin
```

### Update With Force Rebuild

Use this if you have suspicious cache or want clean build:

```bash
# Force clean rebuild with verification
./scripts/update_installed_plugins.nu --force --verify

# Then restart and verify
exit
nu -c "plugin list"
```

### Update Specific Plugin for Testing

```bash
# Check if plugin can be updated
./scripts/update_installed_plugins.nu --plugin nu_plugin_auth --check

# Update just this plugin
./scripts/update_installed_plugins.nu --plugin nu_plugin_auth

# Restart and test
exit
nu -c "plugin list | where name =~ auth"
```

### Manual Registration (if using --no-register)

```bash
# Update without registration
./scripts/update_installed_plugins.nu --no-register

# Register manually later
nu -c "plugin add ~/.local/bin/nu_plugin_auth"
nu -c "plugin add ~/.local/bin/nu_plugin_kms"
nu -c "plugin add ~/.local/bin/nu_plugin_orchestrator"
```

## Troubleshooting

### Plugin Not Found

**Problem**: "Plugin not found or not installed"

**Solution**:
```bash
# List what's installed
ls ~/.local/bin/nu_plugin_*

# List what's available in repo
ls -d nu_plugin_*

# Install plugin first
./scripts/update_installed_plugins.nu  # Updates only installed plugins
```

### Build Failure

**Problem**: Build fails during step 5

**Solution**:
```bash
# Try with verbose output
cd nu_plugin_NAME
cargo build --release

# Or use force rebuild
./scripts/update_installed_plugins.nu --force
```

### Registration Fails

**Problem**: Plugin registers but doesn't work

**Solution**:
```bash
# Remove and re-register manually
nu -c "plugin rm auth"
nu -c "plugin add ~/.local/bin/nu_plugin_auth"

# Restart shell
exit
nu -c "plugin list"
```

### Permission Denied

**Problem**: "Permission denied" when trying to execute

**Solution**:
```bash
# Ensure ~/.local/bin is in PATH
echo $env.PATH | str split (char esep)

# Fix permissions
chmod +x ~/.local/bin/nu_plugin_*

# Ensure ~/.local/bin directory exists and is accessible
ls -ld ~/.local/bin
```

## Integration with Justfile

Add to `justfile` for easy access:

```makefile
# Update installed plugins with full workflow
update-installed-plugins:
    @echo "🔄 Updating installed plugins..."
    @./scripts/update_installed_plugins.nu --verify

# Update specific plugin
update-plugin-from-installed PLUGIN:
    @./scripts/update_installed_plugins.nu --plugin {{PLUGIN}}

# Dry-run before update
check-plugin-updates:
    @./scripts/update_installed_plugins.nu --check
```

Then use:
```bash
just update-installed-plugins
just update-plugin-from-installed nu_plugin_auth
just check-plugin-updates
```

## Comparison: Update Scripts

### `update_all_plugins.nu`
- **Purpose**: Update Cargo.toml dependencies
- **When to use**: Updating Nushell version in cargo files
- **Scope**: Changes source files only
- **Output**: Modified Cargo.toml files
- **Next step**: Must rebuild with `just build`

### `update_installed_plugins.nu` ✨ NEW
- **Purpose**: Update already-installed binaries
- **When to use**: Refresh binaries in ~/.local/bin
- **Scope**: Full cycle: build → install → register
- **Output**: New binaries in ~/.local/bin
- **Includes**: Automatic registration with Nushell

### Typical Workflow

1. **Update source dependencies**
   ```bash
   ./scripts/update_all_plugins.nu 0.108.0
   ```

2. **Rebuild and install**
   ```bash
   ./scripts/update_installed_plugins.nu --force --verify
   ```

3. **Restart and test**
   ```bash
   exit
   nu -c "plugin list"
   ```

## Advanced Usage

### Custom Install Directory (Future Enhancement)

Currently hardcoded to `~/.local/bin`. To support custom directory:

```bash
# Future: Would allow
PLUGIN_INSTALL_DIR=/custom/path ./scripts/update_installed_plugins.nu
```

### Batch Update Multiple Plugins

```bash
# Update in sequence
for plugin in auth kms orchestrator; do
  ./scripts/update_installed_plugins.nu --plugin nu_plugin_$plugin
done
```

### Verify After Update

```bash
# Update with verification
./scripts/update_installed_plugins.nu --verify

# Or verify separately
nu -c "plugin list | format table"
nu -c "plugin list | each {|p| $\"($p.name): ($p.filename)\" }"
```

## Configuration Files

- **Plugin Registry**: `etc/plugin_registry.toml` - Track plugin metadata
- **Common Library**: `scripts/lib/common_lib.nu` - Shared logging functions
- **Build Config**: `Cargo.toml` in each plugin directory

## Support & Issues

For issues or enhancements:
1. Check troubleshooting section above
2. Review script output for specific error messages
3. Run with `--check` first to preview changes
4. Check build output: `cd nu_plugin_NAME && cargo build --release`

## Quick Reference Card

```bash
# DRY RUN (safe, no changes)
./scripts/update_installed_plugins.nu --check

# UPDATE ALL (interactive confirmation)
./scripts/update_installed_plugins.nu

# UPDATE WITH VERIFICATION
./scripts/update_installed_plugins.nu --verify

# UPDATE ONE PLUGIN
./scripts/update_installed_plugins.nu --plugin nu_plugin_NAME

# FORCE REBUILD
./scripts/update_installed_plugins.nu --force

# SKIP REGISTRATION
./scripts/update_installed_plugins.nu --no-register

# THEN RESTART
exit
```

---

**Script Location**: `scripts/update_installed_plugins.nu`
**Install Directory**: `~/.local/bin`
**Created**: 2025-10-22
**Nushell Version**: 0.107.1+