refactor: improve merge implementation quality and performance

[PatrickHeneise]

Summary

Follow-up to #12 - Improves the merge implementation with bug fixes, performance optimizations, and better error handling.

Changes

🐛 Bug Fixes

• Fixed whitespace handling bug: Changed from stripping all whitespace (replace(/\s/g, '')) to trimming only leading/trailing whitespace (.trim())
  • Previously broke values like MESSAGE=Hello World (became HelloWorld)
  • Previously broke database URLs with spaces in passwords
  • Now correctly preserves internal spaces in values

⚡ Performance Improvements

• Optimized duplicate checking: Replaced O(n²) .some() loop with O(n) Set-based lookup
  • Before: checked every key against every example key in nested loop
  • After: build Set once, use O(1) .has() lookups
  • Significant improvement for large .env files

🛡️ Better Error Handling

• Distinguish error types: Added check for ENOENT vs unexpected errors
  • Silently handles expected "file not found" (creates new .env)
  • Logs warnings for unexpected errors (permissions, corruption)
  • Helps users debug issues without failing silently

📚 Documentation Updates

• README.md: Added clear explanation of merge behavior
  • Users upgrading from v1.0.0 now understand the new behavior
  • Explains what happens to existing keys
• CLAUDE.md: Added implementation details and development notes
  • Documents performance optimizations
  • Explains whitespace handling
  • Notes about ESLint version strategy

✅ Test Coverage

• Added test for space preservation in values
• Added integration test for merge with spaces in both new and existing values
• All 12 tests passing

Why These Changes Matter

1. Whitespace bug is critical: Without this fix, any .env value with spaces gets corrupted
2. Performance matters: Large .env files would experience quadratic slowdown
3. Error handling: Users need to know if something unexpected happens vs normal "file not found"

Test Plan

• All 12 tests passing (4 new tests added)
• Lint passing
• Tested with .env files containing spaces in values
• Verified performance improvement with large .env files

🤖 Generated with Claude Code