nushell-plugins/updates/109/MIGRATION_0.109.0.md

# Migration Guide: Nushell 0.109.0

**Date**: 2025-11-30
**From**: 0.108.0
**To**: 0.109.0

## Overview

This guide covers the migration of all 13 plugins from Nushell 0.108.0 to 0.109.0, including the improvements made to the version update system.

## What You Need to Know

### Version Management Changes

#### Smart Version Detection (NEW)
The update process now uses intelligent version management:

1. **Dependency Versions**: Always synchronized with Nushell version (all plugins get 0.109.0)
2. **Package Versions**: Only updated for plugins that tracked Nushell versions
3. **Independent Versions**: Preserved for plugins with their own versioning

Example:
```toml
# Before 0.109.0 update
[package]
version = "0.108.0"        # Tracks Nushell version

[dependencies]
nu-plugin = "0.108.0"      # Gets updated
```

```toml
# After 0.109.0 update
[package]
version = "0.109.0"        # Updated because it was 0.108.0
nu-plugin = "0.109.0"      # Always updated
```

### Script Improvements

#### 1. String Interpolation Fix (Rule 18 Compliance)
**Before**:
```nushell
log_info $"(DRY RUN) Would update ($p.name)"  # ❌ Error: DRY is not a command
```

**After**:
```nushell
log_info $"\(DRY RUN\) Would update ($p.name)"  # ✅ Correct: escaped parentheses
```

#### 2. Template Generation Fix
**Before**:
```nushell
# Generated incorrect filename
install_script | save --force $"($target_path)/install.nu"  # ❌ Wrong name
```

**After**:
```nushell
# Correctly generates register-plugins.nu
install_script | save --force $"($target_path)/register-plugins.nu"  # ✅ Correct
```

**Reason**:
- `install.sh` - Installs binaries to filesystem
- `register-plugins.nu` - Registers plugins with Nushell (doesn't install binaries)

#### 3. Bootstrap Auto-Detection
**Before**:
```bash
# Had to manually specify source path
./install.sh --source-path ./bin
```

**After**:
```bash
# Automatically detects local binaries
./install.sh  # ✅ Auto-detects ./bin/nu or ./nu
```

### Updated Plugins

#### Package Version Updated
- **nu_plugin_clipboard**: 0.108.0 → 0.109.0
  - Had previous Nushell version, so it was automatically updated
  - All 13 plugins still have nu-plugin = 0.109.0 dependency

#### Package Versions Preserved
All other plugins kept their own versions:
- `nu_plugin_auth`: 0.1.0 (custom version)
- `nu_plugin_desktop_notifications`: 1.2.12 (custom version)
- `nu_plugin_fluent`: 0.1.0 (custom version)
- `nu_plugin_hashes`: 0.1.8 (custom version)
- `nu_plugin_highlight`: 1.4.7+0.105.2 (custom version)
- `nu_plugin_image`: 0.105.1 (custom version)
- `nu_plugin_kcl`: 0.1.0 (custom version)
- `nu_plugin_kms`: 0.1.0 (custom version)
- `nu_plugin_orchestrator`: 0.1.0 (custom version)
- `nu_plugin_port_extension`: 0.109.0 (already at Nushell version)
- `nu_plugin_qr_maker`: 1.1.0 (custom version)
- `nu_plugin_tera`: 0.1.0 (custom version)

## Backward Compatibility

### For Future Updates

When updating to **0.110.0** or later, the system will:

1. Calculate the previous version automatically (0.109.0 in this case)
2. Only update plugins that have version = 0.109.0
3. Preserve all independent versions

**Example for 0.110.0 update**:
```nushell
# Plugin versions with 0.109.0 would become 0.110.0
# Others would stay as-is
```

### Breaking Changes

**None** - All plugins are backward compatible with 0.109.0

### Deprecations

**None** - All functionality is preserved

## Installation & Registration

### New Workflow
```bash
# 1. Install binaries
cd distribution/darwin-arm64
./install.sh

# 2. Register plugins with Nushell (doesn't install, just registers)
nu register-plugins.nu

# 3. Verify installation
nu -c 'plugin list'
```

### Old Workflow (Before)
The `install.sh` script now handles both binary installation and has better auto-detection.

## Performance Impact

- **None** - All plugins compile to equivalent binaries
- Build times may vary based on system load
- No runtime performance changes

## Troubleshooting

### Issue: "plugin list" shows old version

**Solution**: Rebuild and re-register
```bash
just build
nu register-plugins.nu
```

### Issue: "DRY RUN error" when running update script

**Solution**: This is fixed in 0.109.0. Ensure you have the latest scripts.

### Issue: install.sh doesn't auto-detect binaries

**Solution**: Ensure you have the latest `installers/bootstrap/install.sh`

## Files Changed

### Modified Scripts
- `scripts/update_all_plugins.nu` - Smart version detection
- `scripts/collect_full_binaries.nu` - Correct template generation
- `scripts/complete_update.nu` - Updated documentation
- `scripts/create_full_distribution.nu` - Updated documentation
- `installers/bootstrap/install.sh` - Auto-detection added

### Modified Documentation
- `CLAUDE.md` - Version updated to 0.109.0

### Plugin Updates
- `nu_plugin_clipboard/Cargo.toml` - Version 0.108.0 → 0.109.0

## Validation Checklist

- [x] All 13 plugins compile successfully
- [x] All plugins have nu-plugin = 0.109.0 dependency
- [x] Package versions are correctly handled (1 updated, 12 preserved)
- [x] Scripts work without string interpolation errors
- [x] Templates generate correct filenames
- [x] Bootstrap installer auto-detects local binaries
- [x] Plugin registration works correctly
- [x] Distribution packages are complete

## Next Steps

1. Review the update summary: `updates/109/UPDATE_SUMMARY.md`
2. Build plugins: `just build`
3. Test: `just test`
4. Create distribution: `just pack-full`
5. Review changes and commit when ready

## Questions or Issues?

Refer to:
- `CLAUDE.md` - Project guidelines and setup
- `guides/COMPLETE_VERSION_UPDATE_GUIDE.md` - Complete update procedures
- `updates/109/UPDATE_SUMMARY.md` - What changed in this update