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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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:

# 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:

# Install nushell first
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install nu

If plugins fail to merge:

# 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:

# Backup exists at plugin_registry.toml.backup
mv plugin_registry.toml.backup plugin_registry.toml