nushell-plugins/updates/108/MIGRATION_0.108.0.md

# Migration Guide: Nushell 0.107.1 → 0.108.0

**Version**: 1.0
**Date**: 2025-10-18
**Target**: Nushell Plugins Repository

---

## Overview

This guide documents the migration process from Nushell 0.107.1 to 0.108.0, including breaking changes, syntax corrections, and required updates for all plugins in this repository.

---

## Critical Syntax Corrections

### 🔴 CRITICAL: These are documentation bugs that were discovered and fixed

Before migrating to 0.108.0, we discovered **TWO CRITICAL BUGS** in our `best_nushell_code.md` documentation that affected ALL code generation. These have been corrected:

#### Bug Fix #1: Function Signature Syntax (Rule 16)

**Problem**: Documentation showed syntax that doesn't work

```nushell
# ❌ INCORRECT (as previously documented)
def process-data [input: string]: table {
    $input | from json
}
# Error: expected arrow (->)
```

**Solution**: Both colon AND arrow are required for pipeline signatures

```nushell
# ✅ CORRECT (now documented properly)
def process-data [input: string]: nothing -> table {
    $input | from json
}
```

**Impact**: ALL scripts using the template pattern need to be updated with `: nothing -> type` syntax.

#### Bug Fix #2: String Interpolation (Rule 17)

**Problem**: Documentation recommended square brackets which don't interpolate

```nushell
# ❌ INCORRECT (as previously documented)
print $"Processing [$filename] at [$timestamp]"
# Output: "Processing [$filename] at [$timestamp]" (LITERAL!)
```

**Solution**: Only parentheses interpolate variables

```nushell
# ✅ CORRECT (now documented properly)
print $"Processing ($filename) at ($timestamp)"
# Output: "Processing data.json at 2025-10-18" (WORKS!)
```

**Impact**: ALL dynamic strings, error messages, and logging need parentheses.

---

## Nushell 0.108.0 Breaking Changes

### 1. Command Rename: `into value` → `detect type`

**What Changed**:
- Command `into value` has been renamed to `detect type`
- Behavior also changed - doesn't operate on cells anymore

**Migration**:

```nushell
# ❌ Old (0.107.1)
$data | into value

# ✅ New (0.108.0)
$data | detect type
```

**Required Actions**:
1. Search for all usages of `into value` in plugin code
2. Replace with `detect type`
3. Review behavior - cell operations may need different approach
4. Test thoroughly as behavior changed

**Search Command**:
```bash
grep -r "into value" nu_plugin_*/src/
```

### 2. Stream Error Handling

**What Changed**:
- Collecting a stream that contains errors now raises an error itself
- Previously, errors in streams were silently collected

**Migration**:

```nushell
# ❌ Old behavior (0.107.1)
let results = ($stream | collect)  # Errors silently included

# ✅ New behavior (0.108.0)
# Must handle errors explicitly
let results = try {
    $stream | collect
} catch {|err|
    log error $"Stream collection failed: ($err.msg)"
    []
}
```

**Required Actions**:
1. Find all stream collection operations
2. Add explicit error handling with `try`/`catch`
3. Test with error-containing streams

**Search Pattern**:
```bash
grep -r "| collect" nu_plugin_*/src/
```

### 3. MCP Feature Addition (New)

**What's New**:
- Nushell now includes Model Context Protocol (MCP) server support
- Feature flag: `mcp`
- New crate: `nu-mcp`

**Usage**:
```bash
# Build with MCP support
cargo build --release --features "mcp,plugin,sqlite,trash-support,system-clipboard"
```

**Integration**:
- MCP server runs on port 8080 by default
- Provides AI agent integration capabilities
- See `nushell/crates/nu-mcp/` for implementation

---

## Plugin Migration Checklist

Use this checklist for each plugin:

### Phase 1: Syntax Corrections

- [ ] Update all function signatures with `: nothing -> type` syntax
- [ ] Replace all `[$var]` string interpolations with `($var)`
- [ ] Test all functions parse correctly
- [ ] Run `cargo check` to verify syntax

### Phase 2: Dependency Updates

- [ ] Update `nu-plugin` dependency to `0.108.0`
- [ ] Update `nu-protocol` dependency to `0.108.0`
- [ ] Update all other `nu-*` dependencies to `0.108.0`
- [ ] Verify path dependencies point to correct nushell submodule

### Phase 3: Breaking Change Fixes

- [ ] Search for `into value` usage
- [ ] Replace with `detect type` and test behavior
- [ ] Find stream collection operations
- [ ] Add explicit error handling for streams
- [ ] Test with error scenarios

### Phase 4: Testing

- [ ] Run `cargo test` for plugin
- [ ] Run `cargo clippy` and fix warnings
- [ ] Build plugin: `cargo build --release`
- [ ] Register plugin with nushell 0.108.0
- [ ] Test plugin functionality end-to-end

### Phase 5: Documentation

- [ ] Update plugin README for 0.108.0
- [ ] Update code examples with correct syntax
- [ ] Document any behavior changes
- [ ] Update version in Cargo.toml

---

## Repository-Wide Migration Steps

### Step 1: Update Nushell Submodule

```bash
# Option A: Using download script (recommended)
./scripts/download_nushell.nu 0.108.0 --clean

# Option B: Using git submodule
cd nushell
git fetch --tags
git checkout 0.108.0
cd ..
git add nushell
```

### Step 2: Update All Plugin Dependencies

```bash
# Automated update
./scripts/update_nu_versions.nu update

# Manual verification
./scripts/update_nu_versions.nu list
```

### Step 3: Fix Syntax Errors

```bash
# Find function signature issues
grep -r "]: [a-z]* {" scripts/ nu_plugin_*/src/

# Find string interpolation issues
grep -r '\$".*\[.*\]' scripts/ nu_plugin_*/src/
```

### Step 4: Build and Test

```bash
# Build nushell with all features
./scripts/build_nushell.nu

# Build all plugins
just build

# Test all plugins
just test

# Quality checks
just quality-flow
```

### Step 5: Verify Installation

```bash
# Register plugins
./scripts/register_plugins.nu

# Verify registration
./nushell/target/release/nu -c "plugin list"

# Test basic functionality
./nushell/target/release/nu -c "version"
```

---

## Common Migration Issues

### Issue 1: Parse Errors in Function Definitions

**Symptom**:
```
Error: Parse mismatch: expected arrow (->) at ]: table {
```

**Solution**: Add `nothing` input type
```nushell
# Before: def fn []: table {
# After:  def fn []: nothing -> table {
```

### Issue 2: Variables Not Interpolating

**Symptom**: String shows literal `[$var]` instead of value

**Solution**: Use parentheses
```nushell
# Before: $"Value: [$var]"
# After:  $"Value: ($var)"
```

### Issue 3: `into value` Not Found

**Symptom**:
```
Error: Command 'into value' not found
```

**Solution**: Use new command name
```nushell
# Before: $data | into value
# After:  $data | detect type
```

### Issue 4: Stream Collection Errors

**Symptom**: Unexpected errors when collecting streams

**Solution**: Add explicit error handling
```nushell
# Before: let results = ($stream | collect)
# After:  let results = try { $stream | collect } catch { [] }
```

### Issue 5: Build Feature Mismatch

**Symptom**: MCP-related build errors

**Solution**: Ensure feature flags are consistent
```bash
cargo build --release --features "mcp,plugin,sqlite,trash-support,system-clipboard,rustls-tls"
```

---

## Testing Strategy

### Unit Tests

```nushell
# Test function signatures parse
def test-signature [x: string]: nothing -> string {
    $x
}

# Test string interpolation
def test-interpolation []: nothing -> string {
    let name = "Alice"
    $"Hello ($name)"
}

# Test error handling
def test-errors []: nothing -> list {
    try {
        error make {msg: "test"}
    } catch {|e|
        [$e.msg]
    }
}
```

### Integration Tests

```bash
# Build with new version
cargo build --release

# Test plugin registration
./nushell/target/release/nu -c "plugin add target/release/nu_plugin_NAME"
./nushell/target/release/nu -c "plugin list"

# Test plugin functionality
./nushell/target/release/nu -c "command-from-plugin"
```

### Regression Tests

```bash
# Verify old functionality still works
just test

# Check performance hasn't degraded
hyperfine './old_version' './new_version'

# Verify output consistency
diff <(./old_version test-data) <(./new_version test-data)
```

---

## Rollback Procedure

If migration fails and you need to rollback:

### Quick Rollback

```bash
# 1. Restore nushell submodule
cd nushell
git checkout 0.107.1
cd ..

# 2. Restore plugin dependencies
git restore nu_plugin_*/Cargo.toml

# 3. Rebuild
cargo clean
cargo build --release
```

### Complete Rollback

```bash
# 1. Create backup first
git stash save "Migration backup"

# 2. Reset to pre-migration state
git reset --hard HEAD~1  # or specific commit

# 3. Rebuild everything
cargo clean
just build
```

---

## Automation Scripts

The following automation scripts were created for this migration:

### Core Scripts

1. **`download_nushell.nu`** - Download Nushell from GitHub tags
   ```bash
   ./scripts/download_nushell.nu 0.108.0 --clean
   ```

2. **`analyze_nushell_features.nu`** - Analyze available features
   ```bash
   ./scripts/analyze_nushell_features.nu --validate --export
   ```

3. **`audit_crate_dependencies.nu`** - Audit plugin dependencies
   ```bash
   ./scripts/audit_crate_dependencies.nu --export
   ```

4. **`detect_breaking_changes.nu`** - Detect breaking API changes
   ```bash
   ./scripts/detect_breaking_changes.nu --scan-plugins
   ```

5. **`update_nushell_version.nu`** - Main orchestrator
   ```bash
   ./scripts/update_nushell_version.nu 0.108.0
   ```

### Script Usage Examples

```bash
# Full automated update (with manual checkpoints)
./scripts/update_nushell_version.nu 0.108.0

# Update to latest release
./scripts/update_nushell_version.nu --latest

# Skip build (faster for testing)
./scripts/update_nushell_version.nu 0.108.0 --skip-build

# Auto-approve all steps (use with caution!)
./scripts/update_nushell_version.nu 0.108.0 --auto-approve

# Check update status
./scripts/update_nushell_version.nu status

# Clean up temporary files
./scripts/update_nushell_version.nu clean
```

---

## Version Compatibility Matrix

| Component | 0.107.1 | 0.108.0 | Compatible |
|-----------|---------|---------|------------|
| nu-plugin | 0.107.1 | 0.108.0 | ✅ Must match |
| nu-protocol | 0.107.1 | 0.108.0 | ✅ Must match |
| Function signatures | `: type {` | `: nothing -> type {` | ❌ Breaking |
| String interpolation | `[$var]` ❌ | `($var)` ✅ | ⚠️ Syntax bug fix |
| `into value` | ✅ Works | ❌ Removed | ❌ Breaking |
| `detect type` | ❌ N/A | ✅ New | ✅ New command |
| Stream errors | Silent | Raises error | ⚠️ Behavior change |
| MCP feature | ❌ N/A | ✅ New | ✅ Optional |

---

## Post-Migration Verification

After completing migration, verify:

### 1. Build Success
```bash
✅ cargo build --release --workspace
✅ All plugins compile without errors
✅ No clippy warnings for migration-related code
```

### 2. Tests Pass
```bash
✅ cargo test --workspace
✅ All unit tests pass
✅ Integration tests pass
```

### 3. Plugins Work
```bash
✅ All plugins register successfully
✅ Plugin commands execute without errors
✅ Plugin output matches expected format
```

### 4. Documentation Updated
```bash
✅ best_nushell_code.md updated with correct syntax
✅ Plugin READMEs reference 0.108.0
✅ Examples use correct syntax
```

### 5. Scripts Updated
```bash
✅ All automation scripts use correct syntax
✅ Scripts parse without errors
✅ Script output is correct
```

---

## Timeline

Expected migration timeline:

- **Preparation**: 30 minutes (read docs, backup)
- **Dependency Update**: 15 minutes (automated)
- **Syntax Fixes**: 1-2 hours (depending on codebase size)
- **Testing**: 1 hour (automated tests + manual verification)
- **Documentation**: 30 minutes
- **Total**: ~3-4 hours for complete migration

---

## Support and Resources

### Official Documentation
- [Nushell 0.108.0 Release Notes](https://github.com/nushell/nushell/releases/tag/0.108.0)
- [Nushell Book](https://www.nushell.sh/book/)
- [Plugin Development Guide](https://www.nushell.sh/book/plugins.html)

### Repository Resources
- `best_nushell_code.md` - Coding standards and patterns
- `NUSHELL_0.108_UPDATE_SUMMARY.md` - Detailed update summary
- `NUSHELL_UPDATE_AUTOMATION.md` - Automation guide
- `etc/plugin_registry.toml` - Plugin tracking

### Getting Help
- Check automation scripts in `scripts/`
- Review git history: `git log --oneline`
- Check build errors: `cargo build 2>&1 | less`

---

## Lessons Learned

### What Went Well
✅ Automated scripts significantly reduced manual work
✅ Testing against actual binary caught documentation bugs
✅ Semi-automated workflow with manual checkpoints prevented mistakes
✅ Comprehensive documentation aided future migrations

### What Could Be Improved
⚠️ Should have validated documentation against binary earlier
⚠️ Need better regression testing for syntax changes
⚠️ Automation scripts should be tested before use
⚠️ Directory naming in download script needs fixing

### Future Improvements
🎯 Add automated syntax validation against binary
🎯 Create regression test suite for common patterns
🎯 Implement CI/CD for version update testing
🎯 Add rollback automation

---

**Migration Guide Version**: 1.0
**Last Updated**: 2025-10-18
**Next Review**: With Nushell 0.109.0 release