nushell-plugins/scripts/README.md

# Nushell Plugin Upstream Tracking System

This system provides automated tracking and management of upstream changes for nushell plugins while preserving your local nu_* dependency modifications.

## 🚀 Quick Start

```bash
# Check status of all plugins
./sh/plugin_status.sh

# Check upstream changes for all plugins
./sh/check_upstream.sh

# Check specific plugin only
./sh/check_upstream.sh --plugin nu_plugin_highlight

# Merge all pending plugins
./sh/safe_merge_upstream.sh --all
```

## 📋 Supported Operations

### ✅ **For ALL Plugins**
```bash
# Check upstream changes for ALL plugins
./sh/check_upstream.sh
nu nu/check_upstream_changes.nu

# Show status of ALL plugins
./sh/plugin_status.sh
nu nu/plugin_status.nu

# Merge ALL pending plugins
./sh/safe_merge_upstream.sh --all
nu nu/safe_merge_upstream.nu --all
```

### ✅ **For ONE Specific Plugin**
```bash
# Check upstream for ONE plugin
./sh/check_upstream.sh --plugin nu_plugin_highlight
nu nu/check_upstream_changes.nu --plugin nu_plugin_highlight

# Preview merge for ONE plugin
./sh/safe_merge_upstream.sh --preview nu_plugin_highlight
nu nu/safe_merge_upstream.nu --preview nu_plugin_highlight

# Merge ONE plugin
./sh/safe_merge_upstream.sh nu_plugin_highlight
nu nu/safe_merge_upstream.nu nu_plugin_highlight
```

### ✅ **For SEVERAL Plugins** (multiple ways)

#### Method 1: Run multiple commands
```bash
# Check several plugins individually
./sh/check_upstream.sh --plugin nu_plugin_highlight
./sh/check_upstream.sh --plugin nu_plugin_clipboard
./sh/check_upstream.sh --plugin nu_plugin_tera

# Merge several plugins individually
./sh/safe_merge_upstream.sh nu_plugin_highlight
./sh/safe_merge_upstream.sh nu_plugin_clipboard
./sh/safe_merge_upstream.sh nu_plugin_tera
```

#### Method 2: Use shell scripting
```bash
# Check multiple plugins in a loop
for plugin in nu_plugin_highlight nu_plugin_clipboard nu_plugin_tera; do
    ./sh/check_upstream.sh --plugin $plugin
done

# Merge multiple specific plugins
for plugin in nu_plugin_highlight nu_plugin_clipboard; do
    ./sh/safe_merge_upstream.sh $plugin
done
```

#### Method 3: Use the "pending" status to target several
```bash
# First, check all to mark them as pending
./sh/check_upstream.sh

# Then merge all pending ones (effectively several plugins)
./sh/safe_merge_upstream.sh --all
```

## 🔧 System Components

### Core Files
- `plugin_registry.toml` - Central configuration and status tracking
- `nu/lib/cargo_toml_diff.nu` - Cargo.toml analysis library
- `nu/check_upstream_changes.nu` - Main upstream checker with auto-OK logic
- `nu/plugin_status.nu` - Status dashboard and management
- `nu/safe_merge_upstream.nu` - Safe merge with rollback capability

### Shell Wrappers (for compatibility)
- `sh/check_upstream.sh` - Shell wrapper for upstream checking
- `sh/plugin_status.sh` - Shell wrapper for status dashboard
- `sh/safe_merge_upstream.sh` - Shell wrapper for safe merging

## 🎯 Auto-OK Logic

The system automatically marks plugins as "OK" when:
- ✅ Only nu_* dependencies changed (nu-plugin, nu-protocol, etc.)
- ✅ No source code changes (.rs files)
- ✅ No other dependency changes
- ✅ Plugin has `auto_ok_on_nu_deps_only = true` in registry

## 📊 Plugin Status Types

| Status | Emoji | Description |
|--------|-------|-------------|
| `ok` | ✅ | Synchronized with upstream |
| `pending` | ⚠️ | Changes detected, needs review |
| `error` | ❌ | Error during checking/merging |
| `conflict` | 🔥 | Merge conflicts detected |
| `unknown` | ❓ | Not yet checked |
| `local_only` | 🏠 | No upstream repository |

## 💡 Usage Examples

### Daily Workflow
```bash
# 1. Check all plugins for updates
./sh/check_upstream.sh

# 2. See what needs attention
./sh/plugin_status.sh attention

# 3. Merge safe updates automatically
./sh/safe_merge_upstream.sh --all

# 4. Review any remaining pending plugins manually
./sh/plugin_status.sh
```

### Specific Plugin Workflow
```bash
# 1. Check one plugin
./sh/check_upstream.sh --plugin nu_plugin_highlight

# 2. Preview what would change
./sh/safe_merge_upstream.sh --preview nu_plugin_highlight

# 3. Merge if acceptable
./sh/safe_merge_upstream.sh nu_plugin_highlight
```

### Batch Processing Several Plugins
```bash
# Define plugins to process
PLUGINS="nu_plugin_highlight nu_plugin_clipboard nu_plugin_tera"

# Check them all
for plugin in $PLUGINS; do
    echo "Checking $plugin..."
    ./sh/check_upstream.sh --plugin $plugin
done

# Show status
./sh/plugin_status.sh

# Merge pending ones
./sh/safe_merge_upstream.sh --all
```

## 🛡️ Safety Features

- **Automatic backups** before any merge
- **Temporary branch testing** before applying changes
- **Rollback capability** if compilation fails
- **Preserves local nu_* versions** during merge
- **Never auto-merges** - only auto-marks as OK
- **Test compilation and tests** after merge

## 🔄 Integration with Existing Scripts

The system integrates with your existing `update_nu_versions.sh`:

```bash
# 1. Check upstream first
./sh/check_upstream.sh

# 2. Update local nu versions
./sh/update_nu_versions.sh

# 3. Check status after update
./sh/plugin_status.sh
```

## 📁 File Structure

```
scripts/
├── plugin_registry.toml           # Central registry
├── nu/                           # Nushell scripts
│   ├── lib/
│   │   └── cargo_toml_diff.nu    # Analysis library
│   ├── check_upstream_changes.nu  # Main checker
│   ├── plugin_status.nu          # Status dashboard
│   └── safe_merge_upstream.nu    # Safe merger
└── sh/                           # Shell wrappers
    ├── check_upstream.sh         # Check wrapper
    ├── plugin_status.sh          # Status wrapper
    └── safe_merge_upstream.sh    # Merge wrapper
```

## ⚙️ Configuration

Edit `plugin_registry.toml` to:
- Add new plugins
- Configure upstream URLs
- Enable/disable auto-OK behavior
- Manage nu_* dependency list

## 🚨 Troubleshooting

### If nushell is not found:
```bash
# Install nushell first
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install nu
```

### If plugins fail to merge:
```bash
# Check individual plugin status
./sh/plugin_status.sh

# Preview changes first
./sh/safe_merge_upstream.sh --preview PLUGIN_NAME

# Force merge if needed
./sh/safe_merge_upstream.sh --force PLUGIN_NAME
```

### If registry gets corrupted:
```bash
# Backup exists at plugin_registry.toml.backup
mv plugin_registry.toml.backup plugin_registry.toml
```