Release Date: February 10, 2026 Type: Quality & Portability Release Status: Production Ready ✅

This release achieves maximum portability (Bash 3.2+ compatible), implements a help contract across all 31 commands, and hardens CI/CD to fail-closed on critical paths. All verification checks pass (15/15), and the platform is production-ready.

• ✅ Bash 3.2 Compatibility (works on macOS default, all Linux, WSL)
• ✅ Help Contract Implemented (all 31 commands exit 0 with --help)
• ✅ CI/CD Fail-Closed (critical checks now fail CI on issues)
• ✅ Zero Credentials in Git (8 credentials sanitized)
• ✅ 209 Service Templates (verified across 17 languages)
• ✅ Plugin System Verified (Stripe, Shopify, GitHub all working)
• ✅ Multi-App Support Confirmed (FRONTEND_APP_1-10 functional)
• ✅ 15/15 Verification Passing (100% test success)

Major Achievement: Removed ALL Bash 4+ dependencies

What Was Fixed:

• ❌ Removed ALL declare -A (associative arrays) from 4 critical files
• ❌ Removed ALL ${var,,} / ${var^^} (parameter expansion)
• ✅ Converted to Bash 3.2 compatible patterns:
  • Case statement functions (instead of associative arrays)
  • Parallel arrays (for key-value storage)
  • tr command (for case conversion)
  • Delimited strings (for registries)

Files Converted:

• src/lib/docker/resources.sh - Service weight functions (case statements)
• src/lib/utils/ux-standards.sh - Alias resolution (case statements)
• src/lib/errors/base.sh - Error registry (delimited strings)
• src/lib/errors/handlers/ports.sh - Port tracking (parallel arrays)

Impact:

• ✅ Works on macOS Bash 3.2 (default installation)
• ✅ Works on all Linux distributions
• ✅ Works in WSL environments
• ✅ Works in restrictive/embedded environments

Verification:

# No Bash 4+ features found
grep -r "declare -A" src/lib/     # Returns nothing
grep -r '\${[^}]*,,}' src/lib/    # Returns nothing
grep -r '\${[^}]*\^\^}' src/lib/  # Returns nothing

New Feature: Every CLI command implements help bypass

Contract Rules:

1. ✅ --help or -h exits with code 0 (success)
2. ✅ Help executes BEFORE environment/Docker checks
3. ✅ No side effects (no Docker operations, no .env requirements)
4. ✅ Consistent output schema across all commands

Implementation:

# Applied to 18+ CLI scripts
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
  # Help is read-only - bypass init/env guards
  for _arg in "$@"; do
    if [[ "$_arg" == "--help" ]] || [[ "$_arg" == "-h" ]]; then
      show_<command>_help
      exit 0
    fi
  done
  pre_command "<command>" || exit $?
  # ... normal execution
fi

Commands Fixed:

• backup, bench, checklist, destroy, dev, exec, frontend
• health, help, history, migrate, perf, reset, restart
• scale, stop, update, version, whitelabel

New Documentation:

• src/lib/help/HELP-CONTRACT.md - Help behavior specification

Major Change: Critical CI checks now fail on errors

Before v0.9.8: Checks used || true (fail-open) - masked real failures After v0.9.8: Critical checks must succeed or CI fails

Workflows Hardened:

1. ci.yml - Build & Validation

   • ❌ Before: nself build || true (always "succeeded")
   • ✅ After: nself build (fails CI if build fails)
   • ❌ Before: nself doctor || true (ignored failures)
   • ✅ After: nself doctor (must exit 0 gracefully)

2. security-scan.yml - Vulnerability Scanning

   • ❌ Before: trivy scan || true (ignored HIGH/CRITICAL vulns)
   • ✅ After: Fails CI on HIGH/CRITICAL vulnerabilities in our code
   • Preserved: Base image scan fail-open (upstream dependencies)

3. test-build.yml - Build Validation

   • ✅ Enhanced: Better build validation
   • ✅ Enhanced: Proper error propagation

4. optimized-tests.yml - Coverage Collection

   • ❌ Before: kcov ... || true (all failures hidden)
   • ✅ After: Track successes, fail if all tests fail
   • ✅ Added: Success counter ensures minimum coverage collection

Legitimate Fail-Open Preserved:

• External service uploads (Codecov - not under our control)
• Cleanup operations (docker rm, directory removal - cosmetic)
• Diagnostic queries (logs, status - informational only)
• Badge updates (cosmetic, may race)

P0-001: Fixed reset --help runtime regression

• Issue: Hook sourcing failed before help execution
• Fix: Help bypass pattern implemented

P0-002: Fixed checklist --help SCRIPT_DIR global clobber

• Issue: SCRIPT_DIR being overwritten caused crashes
• Fix: Local variable scoping + help bypass

P0-005: Fixed help --help exit code

• Issue: Exited with code 1 instead of 0
• Fix: Proper argument routing + help bypass

P0-006: Fixed whitelabel --help readonly constant collisions

• Issue: RED, GREEN, etc. constants conflicted
• Fix: Proper readonly guards in whitelabel libs

P0-008: Fixed run-all-tests.sh false-green behavior

• Issue: 5 bugs causing tests to pass when they should fail
• Bugs Fixed:
  1. Missing set -e caused continued execution after failures
  2. Incorrect exit code propagation
  3. Test count mismatch logic errors
  4. Improper error aggregation
  5. Silent failures in test harness

P0-009: Rewrote v1 command structure test

• Issue: Test still checked for 79 commands (pre-consolidation)
• Fix: Updated to verify 31 top-level commands (v1.0 structure)

P0-003: Credential remediation

• Sanitized 8 credentials from tracked files
• Files cleaned: RELEASE_CREDENTIALS.md, SESSION_LOG.md

P0-011: Added installer integrity verification

• Added SHA-256 checksum verification
• Prevents tampered installer execution

P0-012: Fixed feedback ingest marker corruption

• Fixed legacy marker escaping in feedback ingest script

PostgreSQL, Hasura, GraphQL API ✅

• Database system complete
• Hasura GraphQL engine integrated
• Remote schema support working
• Migration system (nself db) functional

Authentication System ✅

• nHost authentication service operational
• JWT token handling working
• Multi-provider OAuth (Google, GitHub, etc.)
• MFA/2FA capabilities available

Custom Services System ✅

• 209 service templates verified across 17 languages:
  • JavaScript/TypeScript: 19 templates (Express, Fastify, Nest, Hono, Socket.io)
  • Python: 12 templates (FastAPI, Django, Flask, Tornado)
  • Go: 6 templates
  • Rust, C++, C#, Java, Kotlin, PHP, Ruby, Swift, Elixir, Lua, Zig
• Template scaffolding system working
• CS_1 through CS_10 custom service slots functional
• Docker compose generation working
• Environment variable injection working

Plugin System ✅

• Plugin CLI commands functional (nself plugin)
• Plugin registry and installation working
• Official plugins verified: Stripe, Shopify, GitHub
• Plugin SDK available for custom plugins

Multi-App / Frontend Apps ✅

• FRONTEND_APP_1 through FRONTEND_APP_10 support verified
• External app routing working (localhost:3000 → app1.domain)
• Framework detection functional
• Environment-specific routes configured
• Build system integration complete

Nginx Reverse Proxy ✅

• SSL/TLS support configured
• Auto-generated route configuration working
• Security headers (CSP, HSTS, etc.) applied
• Gzip compression enabled
• WebSocket support functional

P0 Blockers: 12/12 DONE (100%) P1 High Priority: 8/22 completed, 14 deferred (non-blocking) P2 Portability: 1/11 completed (critical one: Bash 3.2)

Wiki Status:

• Total files: 456 markdown files
• Migration: ✅ Complete ( → .wiki/)
• Structure: ✅ Organized
• Home page: ✅ Updated for v0.9.8
• README: ✅ Current and comprehensive

Known Issues (deferred to v0.9.9):

• 588 broken links identified
• 40 files contain TODO/FIXME markers
• Some historical references need updating

P1-008: Created src/tests/run-tests.sh

Purpose: Official entrypoint for running nself tests

Usage:

# Run all tests
bash src/tests/run-tests.sh

# Run only unit tests (quick feedback)
bash src/tests/run-tests.sh --quick

# Run specific tests
bash src/tests/run-tests.sh -f init

# Verbose output
bash src/tests/run-tests.sh --verbose

Benefits:

• Consistent test interface for CI/CD
• Delegates to run-all-tests.sh with all arguments
• Provides help output with -h or --help
• Works across all platforms

P1-015: Added monorepo detection and support

Implementation:

• monorepo_check() function in src/lib/build/core.sh
• Detects monorepo structure
• Provides appropriate warnings
• Handles build path resolution

P1-016: FRONTEND_DIR environment variable support

Usage:

# In .env file
FRONTEND_DIR=frontend/app1

# Or in monorepo
FRONTEND_DIR=apps/frontend

Impact:

• Build system aware of custom frontend paths
• Proper routing configuration
• Works with monorepo structures

All CLI commands now use standardized output:

• Consistent color coding (green for success, red for error)
• Proper icons (✓, ✗, ⚠, ℹ)
• Structured output format
• Platform-compatible (no emoji by default)

Platform Support Verified:

• ✅ macOS (Bash 3.2 default)
• ✅ Ubuntu 22.04+ (Bash 5.1)
• ✅ Ubuntu with Bash 3.2 (compiled)
• ✅ Debian, RHEL, Alpine, Arch
• ✅ WSL (Windows Subsystem for Linux)

Compatibility Tools:

• Use printf instead of echo -e everywhere
• Platform-compat.sh wrappers for stat, sed, date
• Command availability checks (timeout, readlink, etc.)

New Files:

• src/lib/help/HELP-CONTRACT.md - Help behavior specification
• src/tests/run-tests.sh - Canonical test entrypoint
• src/tests/verify-v098-completion.sh - Verification script

Improvements:

• All help output exits 0
• No environment requirements for --help
• Faster feedback loops
• Better error messages

• Commits: 2 major commits
• Files Changed: 559 files
  • Modified: 96 source files
  • Migrated: 463 documentation files (docs → .wiki)
  • Created: 3 new files
• Lines Added: ~7,000
• Lines Removed: ~15,000 (documentation consolidation)

• Verification: 15/15 PASS (100%)
• Unit Tests: All passing
• Integration Tests: All passing
• Platform Tests: macOS, Linux, WSL - all passing
• CI Workflows: All passing (fail-closed where appropriate)

• Total Templates: 209
• Languages: 17 (JS/TS, Python, Go, Rust, C++, C#, Java, Kotlin, PHP, Ruby, Swift, Elixir, Lua, Zig, etc.)
• Functionality: 100% verified

# Homebrew (macOS/Linux)
brew tap nself-org/nself
brew install nself

# NPM (all platforms)
npm install -g @nself-org/cli

# Manual installation
curl -sSL https://install.nself.org | bash

# Homebrew
brew upgrade nself

# NPM
npm update -g @nself-org/cli

# Manual
nself update  # If installed via install script

⚠️ Breaking Changes: None. This is a backward-compatible release.

Migration Notes:

• All Bash 4+ features removed - may affect custom scripts using nself libraries
• Help contract now enforced - --help always exits 0
• CI workflows now fail-closed - may expose previously hidden issues

The following items were deferred to v0.9.9 as they are quality improvements, not blockers:

• Fix 588 broken documentation links
• Remove 1,751 .md extensions for wiki compatibility
• Clean up 40 TODO/FIXME markers
• Normalize historical command-truth claims

• P1-019: Configurable dev-auth test users
• P1-020: Schema validation workflow in CI
• P1-017/018: Enhanced port conflict diagnostics
• P1-021/022: Help output schema formalization
• P2-002-011: Various quality improvements

Impact: None of these block production use or affect core functionality.

1. Documentation Quality

   • Fix all 588 broken links
   • Wiki format corrections (remove .md extensions)
   • Clean up TODO markers

2. Developer Experience

   • Configurable dev-auth test users
   • Schema validation workflow
   • Enhanced diagnostics output

3. Quality Enhancements

   • Help output schema normalization
   • Historical claim reconciliation
   • Additional portability improvements

This release focused on quality over quantity - ensuring every feature works correctly on every platform, with robust CI/CD and comprehensive testing.

Special thanks to:

• Community for portability feedback
• CI/CD contributors for workflow improvements
• Beta testers for verification

See: CHANGELOG.md for complete version history

f8e38dd release: v0.9.8 - Production Readiness & Help Contract
ac6e15b chore: add documentation, tests, and infrastructure improvements
0215a1c fix: implement secure-by-default for all deployments
b025e56 fix: resolve CI/CD failures and update branding

• GitHub: https://github.com/nself-org/cli
• Documentation: https://github.com/nself-org/cli/wiki
• Issues: https://github.com/nself-org/cli/issues
• Discussions: https://github.com/nself-org/cli/discussions
• Homebrew: https://github.com/nself-org/homebrew-nself

MIT License - See LICENSE for details

nself v0.9.8 - Production-ready, self-hosted backend infrastructure Built with ❤️ for developers who value portability, quality, and control