v0.4.1

nself cli v0.4.1

Release Date: January 17, 2026 Focus: Bug Fixes & Platform Compatibility

---

Overview

v0.4.1 is a bug fix release that addresses 5 critical platform compatibility issues discovered during the v0.4.0 QA audit. This release ensures nself works correctly on both macOS and Linux without any platform-specific failures.

What's Fixed

• ✅ Bash 3.2 Compatibility: Fixed array declaration syntax
• ✅ Cross-Platform sed: Fixed in-place editing for macOS/Linux
• ✅ Cross-Platform stat: Fixed file stat commands
• ✅ Portable timeout: Added guards for timeout command
• ✅ Portable output: Converted echo -e to printf in critical files

---

Bug Fixes

🔴 Critical Fix #1: Bash 4+ Feature in start.sh

Issue: Line 119 used declare -a PROGRESS_STEPS=() which is Bash 4+ only syntax Impact: Breaks on macOS which ships with Bash 3.2 Fix: Changed to Bash 3.2 compatible PROGRESS_STEPS=()

Files Changed:

• src/cli/start.sh

---

🔴 Critical Fix #2: sed -i Platform Compatibility

Issue: sed -i.bak works on GNU sed (Linux) but fails on BSD sed (macOS) Impact: Configuration updates fail on macOS Fix: Use safe_sed_inline() wrapper from platform-compat.sh

Files Changed:

• src/cli/admin.sh - 3 occurrences fixed
• src/cli/deploy.sh - 8 occurrences fixed
• src/lib/init/wizard/templates.sh - 10 occurrences fixed
• src/lib/autofix/pre-checks.sh - 1 occurrence fixed

---

🔴 Critical Fix #3: stat Command Platform Differences

Issue: stat -f (macOS) vs stat -c (Linux) have different syntax Impact: File modification time checks fail on wrong platform Fix: Use safe_stat_mtime() and safe_stat_perms() wrappers or platform detection

Files Changed:

• src/lib/monitoring/alerting.sh - Added platform detection

Note: Most files already had fallback patterns stat -f ... || stat -c ...

---

🔴 Critical Fix #4: timeout Command Availability

Issue: timeout command doesn't exist on macOS by default Impact: Commands hang indefinitely or fail with "command not found" Fix: Use safe_timeout() wrapper from platform-compat.sh

Files Changed:

• src/cli/restart.sh - 2 occurrences fixed
• src/cli/status.sh - 2 occurrences fixed
• src/services/docker/compose-generate.sh - 2 occurrences fixed
• src/services/docker/compose-generate-new.sh - 1 occurrence fixed
• src/lib/autofix/pre-checks.sh - 3 occurrences fixed
• src/lib/services/routes-display.sh - 1 occurrence fixed

---

🟠 High Priority Fix #5: echo -e Usage

Issue: echo -e is not portable and behaves inconsistently across shells Impact: Output formatting may be incorrect on some systems Fix: Convert to printf for formatted output

Files Changed:

• src/cli/stop.sh - All echo -e converted to printf

---

Platform Compatibility Library

These platform-safe wrapper functions are now used throughout the codebase:

Function	Purpose	Replaces
safe_sed_inline()	Cross-platform in-place sed	sed -i / sed -i ''
safe_stat_mtime()	Get file modification time	stat -f %m / stat -c %Y
safe_stat_perms()	Get file permissions	stat -f %OLp / stat -c %a
safe_timeout()	Timeout with fallback	timeout / gtimeout
safe_readlink()	Resolve symlinks	readlink -f

Location: src/lib/utils/platform-compat.sh

---

Upgrade Instructions

From v0.4.0

This is a bug fix release with no breaking changes. Simply update nself:

nself update

Or manually:

cd /path/to/nself
git pull origin main

---

Testing Verification

All changes have been verified to work on:

• ✅ Ubuntu 22.04 (Bash 5.1, GNU tools)
• ✅ macOS (Bash 3.2, BSD tools)
• ✅ CI Pipeline (12/12 tests passing)

---

Known Issues

No known issues in v0.4.1.

---

Roadmap

v0.4.2 (Next)

• Add basic tests for start/stop commands
• Telemetry infrastructure (opt-out)
• Documentation updates

v0.4.3 and Beyond

• Deploy command improvements
• Database operations
• Backup/restore enhancements

---

Full Changelog

See CHANGELOG.md for complete history.