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

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

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

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

Solution: Only parentheses interpolate variables

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

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

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:

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

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:

# 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

# 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

# Automated update
./scripts/update_nu_versions.nu update

# Manual verification
./scripts/update_nu_versions.nu list

Step 3: Fix Syntax Errors

# 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

# 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

# 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

# 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

# Before: $"Value: [$var]"
# After:  $"Value: ($var)"

Issue 3: into value Not Found

Symptom:

Error: Command 'into value' not found

Solution: Use new command name

# Before: $data | into value
# After:  $data | detect type

Issue 4: Stream Collection Errors

Symptom: Unexpected errors when collecting streams

Solution: Add explicit error handling

# 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

cargo build --release --features "mcp,plugin,sqlite,trash-support,system-clipboard,rustls-tls"

---

Testing Strategy

Unit Tests

# 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

# 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

# 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

# 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

# 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

   ./scripts/download_nushell.nu 0.108.0 --clean
   

2. analyze_nushell_features.nu - Analyze available features

   ./scripts/analyze_nushell_features.nu --validate --export
   

3. audit_crate_dependencies.nu - Audit plugin dependencies

   ./scripts/audit_crate_dependencies.nu --export
   

4. detect_breaking_changes.nu - Detect breaking API changes

   ./scripts/detect_breaking_changes.nu --scan-plugins
   

5. update_nushell_version.nu - Main orchestrator

   ./scripts/update_nushell_version.nu 0.108.0
   

Script Usage Examples

# 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

✅ cargo build --release --workspace
✅ All plugins compile without errors
✅ No clippy warnings for migration-related code

2. Tests Pass

✅ cargo test --workspace
✅ All unit tests pass
✅ Integration tests pass

3. Plugins Work

✅ All plugins register successfully
✅ Plugin commands execute without errors
✅ Plugin output matches expected format

4. Documentation Updated

✅ best_nushell_code.md updated with correct syntax
✅ Plugin READMEs reference 0.108.0
✅ Examples use correct syntax

5. Scripts Updated

✅ 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
• Nushell Book
• Plugin Development Guide

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