# Nushell Plugin Upstream Tracking System\n\nThis system provides automated tracking and management of upstream changes for nushell plugins while preserving your local nu_* dependency modifications.\n\n## 🚀 Quick Start\n\n```bash\n# Check status of all plugins\n./sh/plugin_status.sh\n\n# Check upstream changes for all plugins\n./sh/check_upstream.sh\n\n# Check specific plugin only\n./sh/check_upstream.sh --plugin nu_plugin_highlight\n\n# Merge all pending plugins\n./sh/safe_merge_upstream.sh --all\n```\n\n## 📋 Supported Operations\n\n### ✅ **For ALL Plugins**\n\n```bash\n# Check upstream changes for ALL plugins\n./sh/check_upstream.sh\nnu nu/check_upstream_changes.nu\n\n# Show status of ALL plugins\n./sh/plugin_status.sh\nnu nu/plugin_status.nu\n\n# Merge ALL pending plugins\n./sh/safe_merge_upstream.sh --all\nnu nu/safe_merge_upstream.nu --all\n```\n\n### ✅ **For ONE Specific Plugin**\n\n```bash\n# Check upstream for ONE plugin\n./sh/check_upstream.sh --plugin nu_plugin_highlight\nnu nu/check_upstream_changes.nu --plugin nu_plugin_highlight\n\n# Preview merge for ONE plugin\n./sh/safe_merge_upstream.sh --preview nu_plugin_highlight\nnu nu/safe_merge_upstream.nu --preview nu_plugin_highlight\n\n# Merge ONE plugin\n./sh/safe_merge_upstream.sh nu_plugin_highlight\nnu nu/safe_merge_upstream.nu nu_plugin_highlight\n```\n\n### ✅ **For SEVERAL Plugins** (multiple ways)\n\n#### Method 1: Run multiple commands\n\n```bash\n# Check several plugins individually\n./sh/check_upstream.sh --plugin nu_plugin_highlight\n./sh/check_upstream.sh --plugin nu_plugin_clipboard\n./sh/check_upstream.sh --plugin nu_plugin_tera\n\n# Merge several plugins individually\n./sh/safe_merge_upstream.sh nu_plugin_highlight\n./sh/safe_merge_upstream.sh nu_plugin_clipboard\n./sh/safe_merge_upstream.sh nu_plugin_tera\n```\n\n#### Method 2: Use shell scripting\n\n```bash\n# Check multiple plugins in a loop\nfor plugin in nu_plugin_highlight nu_plugin_clipboard nu_plugin_tera; do\n    ./sh/check_upstream.sh --plugin $plugin\ndone\n\n# Merge multiple specific plugins\nfor plugin in nu_plugin_highlight nu_plugin_clipboard; do\n    ./sh/safe_merge_upstream.sh $plugin\ndone\n```\n\n#### Method 3: Use the "pending" status to target several\n\n```bash\n# First, check all to mark them as pending\n./sh/check_upstream.sh\n\n# Then merge all pending ones (effectively several plugins)\n./sh/safe_merge_upstream.sh --all\n```\n\n## 🔧 System Components\n\n### Core Files\n\n- `plugin_registry.toml` - Central configuration and status tracking\n- `nu/lib/cargo_toml_diff.nu` - Cargo.toml analysis library\n- `nu/check_upstream_changes.nu` - Main upstream checker with auto-OK logic\n- `nu/plugin_status.nu` - Status dashboard and management\n- `nu/safe_merge_upstream.nu` - Safe merge with rollback capability\n\n### Shell Wrappers (for compatibility)\n\n- `sh/check_upstream.sh` - Shell wrapper for upstream checking\n- `sh/plugin_status.sh` - Shell wrapper for status dashboard\n- `sh/safe_merge_upstream.sh` - Shell wrapper for safe merging\n\n## 🎯 Auto-OK Logic\n\nThe system automatically marks plugins as "OK" when:\n\n- ✅ Only nu_* dependencies changed (nu-plugin, nu-protocol, etc.)\n- ✅ No source code changes (.rs files)\n- ✅ No other dependency changes\n- ✅ Plugin has `auto_ok_on_nu_deps_only = true` in registry\n\n## 📊 Plugin Status Types\n\n| Status | Emoji | Description |\n|--------|-------|-------------|\n| `ok` | ✅ | Synchronized with upstream |\n| `pending` | ⚠️ | Changes detected, needs review |\n| `error` | ❌ | Error during checking/merging |\n| `conflict` | 🔥 | Merge conflicts detected |\n| `unknown` | ❓ | Not yet checked |\n| `local_only` | 🏠 | No upstream repository |\n\n## 💡 Usage Examples\n\n### Daily Workflow\n\n```bash\n# 1. Check all plugins for updates\n./sh/check_upstream.sh\n\n# 2. See what needs attention\n./sh/plugin_status.sh attention\n\n# 3. Merge safe updates automatically\n./sh/safe_merge_upstream.sh --all\n\n# 4. Review any remaining pending plugins manually\n./sh/plugin_status.sh\n```\n\n### Specific Plugin Workflow\n\n```bash\n# 1. Check one plugin\n./sh/check_upstream.sh --plugin nu_plugin_highlight\n\n# 2. Preview what would change\n./sh/safe_merge_upstream.sh --preview nu_plugin_highlight\n\n# 3. Merge if acceptable\n./sh/safe_merge_upstream.sh nu_plugin_highlight\n```\n\n### Batch Processing Several Plugins\n\n```bash\n# Define plugins to process\nPLUGINS="nu_plugin_highlight nu_plugin_clipboard nu_plugin_tera"\n\n# Check them all\nfor plugin in $PLUGINS; do\n    echo "Checking $plugin..."\n    ./sh/check_upstream.sh --plugin $plugin\ndone\n\n# Show status\n./sh/plugin_status.sh\n\n# Merge pending ones\n./sh/safe_merge_upstream.sh --all\n```\n\n## 🛡️ Safety Features\n\n- **Automatic backups** before any merge\n- **Temporary branch testing** before applying changes\n- **Rollback capability** if compilation fails\n- **Preserves local nu_* versions** during merge\n- **Never auto-merges** - only auto-marks as OK\n- **Test compilation and tests** after merge\n\n## 🔄 Integration with Existing Scripts\n\nThe system integrates with your existing `update_nu_versions.sh`:\n\n```bash\n# 1. Check upstream first\n./sh/check_upstream.sh\n\n# 2. Update local nu versions\n./sh/update_nu_versions.sh\n\n# 3. Check status after update\n./sh/plugin_status.sh\n```\n\n## 📁 File Structure\n\n```plaintext\nscripts/\n├── plugin_registry.toml           # Central registry\n├── nu/                           # Nushell scripts\n│   ├── lib/\n│   │   └── cargo_toml_diff.nu    # Analysis library\n│   ├── check_upstream_changes.nu  # Main checker\n│   ├── plugin_status.nu          # Status dashboard\n│   └── safe_merge_upstream.nu    # Safe merger\n└── sh/                           # Shell wrappers\n    ├── check_upstream.sh         # Check wrapper\n    ├── plugin_status.sh          # Status wrapper\n    └── safe_merge_upstream.sh    # Merge wrapper\n```\n\n## ⚙️ Configuration\n\nEdit `plugin_registry.toml` to:\n\n- Add new plugins\n- Configure upstream URLs\n- Enable/disable auto-OK behavior\n- Manage nu_* dependency list\n\n## 🚨 Troubleshooting\n\n### If nushell is not found\n\n```bash\n# Install nushell first\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\ncargo install nu\n```\n\n### If plugins fail to merge\n\n```bash\n# Check individual plugin status\n./sh/plugin_status.sh\n\n# Preview changes first\n./sh/safe_merge_upstream.sh --preview PLUGIN_NAME\n\n# Force merge if needed\n./sh/safe_merge_upstream.sh --force PLUGIN_NAME\n```\n\n### If registry gets corrupted\n\n```bash\n# Backup exists at plugin_registry.toml.backup\nmv plugin_registry.toml.backup plugin_registry.toml\n```