Skip to content

ROADMAP.adoc

Latest commit

 

History

History
582 lines (431 loc) · 14.7 KB

ROADMAP.adoc

File metadata and controls

582 lines (431 loc) · 14.7 KB

Modshells Development Roadmap

Development roadmap for Modshells, the modular shell configuration manager.

Contents

Current State: v0.0 (Alpha)

What Exists

Component Description Status

modshells.adb

Main entry point, initialisation flow

Complete

Config_Store

Path resolution from env vars, home directory detection

Complete

Shell_Manager.Create_Modshell_Directories

Idempotent directory creation (core, tools, misc, os, ui)

Complete

Shell_Manager.Detect_Shells

Shell detection (10 shell types enumerated)

Stub only

Shell_Manager.Is_Modularized

Signature-based idempotency check

Partial

Shell_Manager.Modularise_Config

Backup + injection logic

Stub only

Build system

GPRBuild project files, CI/CD

Complete

Documentation

README, Contributing, Security, Citations

Complete

Milestone 1: Core Functionality

Complete the foundational shell management capabilities.

1.1 Shell Detection

Implement actual shell detection to replace the current stub.

  • ❏ Detect installed shells via which / command -v

  • ❏ Detect shells listed in /etc/shells

  • ❏ Handle non-standard installation paths

  • ❏ Return accurate Shell_Status (Installed, Not_Installed, Can_Be_Installed)

  • ❏ Test on multiple Linux distributions

1.2 Configuration File Location

Map each shell type to its configuration file(s).

  • ❏ Define config file paths per shell

    • Bash: ~/.bashrc, ~/.bash_profile

    • Zsh: ~/.zshrc, ~/.zprofile

    • Fish: ~/.config/fish/config.fish

    • Nushell: ~/.config/nushell/config.nu

    • Ion: ~/.config/ion/initrc

    • Oils: ~/.oshrc, ~/.yshrc

    • Tcsh: ~/.tcshrc, ~/.cshrc

    • Ksh: ~/.kshrc

    • Dash: requires ENV variable

    • PowerShell: profile paths vary by platform

  • ❏ Handle XDG Base Directory specification

  • ❏ Support custom config locations

1.3 Configuration Backup

Implement safe backup before modification.

  • ❏ Create timestamped backup: .bashrc.modshells-backup-20240101-120000

  • ❏ Configurable backup location

  • ❏ Backup rotation (keep N most recent)

  • ❏ Verify backup integrity before proceeding

1.4 Source Injection

Inject sourcing logic into shell configurations.

  • ❏ Generate shell-specific sourcing syntax

    • POSIX shells: for f in dir/*.sh; do . "$f"; done

    • Fish: for f in dir/*.fish; source $f; end

    • Nushell: source with glob

    • PowerShell: Get-ChildItem | ForEach-Object { . $_ }

  • ❏ Inject between signature markers

  • ❏ Handle different file extension conventions

  • ❏ Respect alphabetical ordering of sourced files

Milestone 2: Multi-Shell Orchestration

2.1 Unified Modularisation

  • ❏ modshells init - Modularise all detected shells

  • ❏ modshells init --shell=bash,zsh - Modularise specific shells

  • ❏ Interactive mode with shell selection

  • ❏ Dry-run mode (--dry-run) showing planned changes

2.2 Shell-Agnostic Configuration

  • ❏ Define .modshells extension for cross-shell configs

  • ❏ Transpilation layer for common syntax

    • Common aliases → shell-specific syntax

    • Environment variables (portable)

    • Path modifications

  • ❏ Fall back to shell-specific files when needed

2.3 Synchronisation

  • ❏ Detect config drift (manual edits to modularised files)

  • ❏ Re-sync modular structure from monolithic backup

  • ❏ Import existing configurations into modular structure

Milestone 3: Configuration Management

3.1 Snippet Management

  • ❏ modshells add <category> <name> - Create new snippet

  • ❏ modshells list - List all snippets by category

  • ❏ modshells enable/disable <snippet> - Toggle snippets

  • ❏ Template system for common configurations

3.2 Categories and Ordering

  • ❏ Configurable category directories

  • ❏ Explicit ordering via manifest file

  • ❏ Dependency declaration between snippets

  • ❏ Conditional loading (by hostname, OS, etc.)

3.3 Validation

  • ❏ Syntax checking before injection

  • ❏ Lint shell configurations

  • ❏ Detect conflicting aliases/functions

  • ❏ Security audit (no exposed secrets)

Milestone 4: Distribution and Integration

4.1 Package Distribution

  • ❏ Guix package definition (guix.scm)

  • ❏ Nix flake (flake.nix)

  • ❏ Binary releases for common platforms

  • ❏ Container image for CI/CD integration

4.2 Integration

  • ❏ Starship prompt integration

  • ❏ Direnv compatibility

  • ❏ asdf/mise version manager integration

  • ❏ Shell plugin manager compatibility (oh-my-zsh, fisher, etc.)

4.3 Migration Tools

  • ❏ Import from oh-my-zsh

  • ❏ Import from prezto

  • ❏ Import from bash-it

  • ❏ Export to portable format

Milestone 5: Comprehensive Validation (NEW)

The Shell Validator provides comprehensive validation, verification, and security analysis.

5.1 Syntax and Sequence Validation

  • ❏ Validate_Syntax - Run bash -n and shellcheck

  • ❏ Validate_Command_Sequence - Ensure correct ordering (exports before use)

  • ❏ Detect_Infinite_Loops - Static analysis for potential loops

  • ❏ Detect_Skipped_Blocks - Dead code detection

5.2 Directory and File Validation

  • ❏ Validate_Directory_Structure - Check modular structure

  • ❏ Validate_Symlinks - Verify all symlinks are valid

  • ❏ Validate_File_Presence - Check required files exist

  • ❏ Validate_Completeness - No orphaned modules

5.3 Permission Validation

  • ❏ Validate_Permissions - Correct read/write/execute

  • ❏ Validate_Ownership - File owned by current user

  • ❏ Detect_World_Writable - Security risk detection

  • ❏ Detect_SUID_SGID - Inappropriate permission bits

5.4 Duplication Detection

  • ❏ Detect_Duplicate_Aliases - Find duplicate alias definitions

  • ❏ Detect_Duplicate_Functions - Find duplicate function definitions

  • ❏ Detect_Duplicate_Exports - Find duplicate exports

  • ❏ Detect_Path_Duplicates - Find duplicate PATH entries

  • ❏ Detect_Conflicting_Settings - Find overriding settings

5.5 POSIX Compliance

  • ❏ Validate_POSIX_Compliance - Strict/Relaxed/Extended levels

  • ❏ Detect_Bashisms - Find bash-specific syntax

  • ❏ Validate_Portable_Syntax - Cross-shell compatibility

5.6 Performance Analysis

  • ❏ Analyze_Load_Time - Profile shell startup

  • ❏ Detect_Slow_Commands - Find slow initialization

  • ❏ Suggest_Lazy_Loading - Deferred loading candidates

  • ❏ Analyze_Execution_Flow - Optimal load order

5.7 Security Validation

  • ❏ Detect_Hardcoded_Secrets - Find exposed credentials

  • ❏ Detect_Dangerous_Commands - rm -rf, eval, exec

  • ❏ Validate_Input_Sanitization - Proper quoting

  • ❏ Check_CVE_Vulnerabilities - Known shell CVEs

  • ❏ Validate_Sudo_Usage - Safe sudo patterns

5.8 SELinux and Firewall Compatibility

  • ❏ Validate_SELinux_Context - Appropriate contexts

  • ❏ Detect_SELinux_Conflicts - Policy violations

  • ❏ Validate_Firewall_Safety - Network command safety

5.9 Tool Integration Validation

  • ❏ Validate_Starship_Config - Prompt configuration

  • ❏ Validate_Completion_Setup - bash-completion, carapace

  • ❏ Validate_Direnv_Integration - Hook placement

  • ❏ Validate_Asdf_Integration - Version manager setup

  • ❏ Validate_Atuin_Integration - History sync

5.10 Formal Verification

  • ❏ Run_Formal_Verification - ShellCheck, BATS, Pyre

  • ❏ Generate_Verification_Report - Comprehensive report

  • ❏ Export_For_Theorem_Prover - Experimental prover export

5.11 Annotation and Metadata

  • ❏ Validate_SPDX_Headers - License headers

  • ❏ Validate_Annotations - Required comments

  • ❏ Check_Documentation_Coverage - Function documentation

Milestone 6: Advanced Features

6.1 Remote Configuration

  • ❏ Sync configurations via Git

  • ❏ Encrypted secrets handling

  • ❏ Machine-specific overlays

  • ❏ Dotfiles repository integration

5.2 Shell Session Management

  • ❏ Profile switching (work/personal)

  • ❏ Temporary configuration injection

  • ❏ Session isolation

5.3 Observability

  • ❏ Shell startup time profiling

  • ❏ Configuration load tracing

  • ❏ Audit log of modifications

Technical Debt

Code Quality

  • ❏ Replace mock paths in Is_Modularized with actual config paths

  • ❏ Implement comprehensive error messages

  • ❏ Add logging with configurable verbosity

  • ❏ Unit test suite with AUnit

Build System

  • ❏ Complete justfile recipes (build, test, clean, fmt, lint)

  • ❏ Add development container (.devcontainer)

  • ❏ Cross-compilation for macOS and Windows

  • ❏ Static linking for portable binaries

Documentation

  • ❏ Man page (modshells.1)

  • ❏ Shell completion scripts (bash, zsh, fish, nushell)

  • ❏ Tutorial: "Modularising Your Shell in 5 Minutes"

  • ❏ Architecture Decision Records (ADRs)

Appendix A: POSIX Shell Validation Roadmap

Validation support for POSIX-compliant shells. The Shell Validator will provide equivalent validation capabilities for all POSIX shells.

A.1 POSIX Shell Matrix

Shell Config Files Special Considerations Priority

sh (Bourne)

/etc/profile, ~/.profile

Strictest POSIX compliance, no arrays

High

dash

ENV variable, ~/.profile

Debian/Ubuntu /bin/sh, fastest startup

High

bash

~/.bashrc, ~/.bash_profile

Most common, extensive extensions

Complete

ksh (KornShell)

~/.kshrc, ~/.profile

POSIX superset, advanced features

Medium

zsh

~/.zshrc, ~/.zprofile, ~/.zshenv

Extensive customisation, oh-my-zsh ecosystem

High

ash (BusyBox)

ENV variable

Embedded systems, Alpine Linux

Medium

mksh

~/.mkshrc

Android shell, MirBSD

Low

yash

~/.yashrc

Strictest POSIX compliance

Low

A.2 POSIX Validation Features

Each POSIX shell will support:

  • ❏ Syntax validation using shell’s native -n flag

  • ❏ POSIX compliance level checking (strict/relaxed)

  • ❏ Shell-specific extension detection

  • ❏ Configuration file location resolution

  • ❏ Startup script ordering validation

  • ❏ Environment variable inheritance checking

  • ❏ Signal handling validation

  • ❏ Exit code propagation analysis

A.3 Cross-Shell Portability Testing

  • ❏ Generate portable shell scripts from modular configs

  • ❏ Test execution across sh, dash, bash, ksh, zsh

  • ❏ Report shell-specific incompatibilities

  • ❏ Suggest portable alternatives for non-portable constructs

Appendix B: Non-POSIX Shell Compatibility

Support for modern non-POSIX shells requires different validation strategies.

B.1 Non-POSIX Shell Matrix

Shell Config Files Language/Paradigm Compatibility Notes

Fish

~/.config/fish/config.fish

Not POSIX, user-friendly syntax

No $(), uses (command). No export, uses set -x. Different quoting rules.

Nushell

~/.config/nushell/config.nu

Structured data, tables as first-class

Completely different paradigm. Pipeline operates on structured data, not text.

Elvish

~/.config/elvish/rc.elv

Functional, structured values

Different variable syntax ($var vs set var). Rich data types.

Ion

~/.config/ion/initrc

Rust-inspired, typed

Method syntax on variables. Strong typing. Array operations differ.

Oils (osh/ysh)

~/.oshrc, ~/.yshrc

POSIX-compatible (osh) + enhanced (ysh)

osh is POSIX-compatible. ysh adds JSON, expressions, better errors.

PowerShell

$PROFILE (varies by platform)

Object-oriented, .NET based

Completely different. Cmdlets, objects in pipeline, -Verb-Noun naming.

Tcsh/Csh

~/.tcshrc, ~/.cshrc

C-like syntax

Different syntax for everything. Avoid for scripting (historical only).

Xonsh

~/.xonshrc

Python + shell hybrid

Python syntax mixed with shell. Import Python directly.

Murex

~/.murex_profile

Type-aware, safety-focused

Strong typing, safer defaults, different pipeline semantics.

B.2 Non-POSIX Validation Strategy

For each non-POSIX shell, implement:

Fish

  • ❏ Native syntax validation (fish -n)

  • ❏ Universal variable handling

  • ❏ Abbreviation vs alias distinction

  • ❏ Function autoloading paths

  • ❏ Fisher/oh-my-fish plugin detection

Nushell

  • ❏ Native syntax validation

  • ❏ Module system validation

  • ❏ Hook configuration (env_change, pre_prompt)

  • ❏ Plugin registration

  • ❏ Structured config validation (TOML-based)

Elvish

  • ❏ Native syntax validation

  • ❏ Module import validation

  • ❏ Edit mode configuration

  • ❏ Persistent variable handling

Ion

  • ❏ Native syntax validation

  • ❏ Method call validation

  • ❏ Array type checking

  • ❏ Plugin/builtin validation

Oils (osh/ysh)

  • ❏ osh: POSIX validation

  • ❏ ysh: Enhanced syntax validation

  • ❏ Expression evaluation safety

  • ❏ JSON/YAML parsing in configs

PowerShell

  • ❏ Native syntax validation (Test-ScriptFileInfo)

  • ❏ Module manifest validation

  • ❏ Execution policy compliance

  • ❏ Cross-platform path handling (Windows/Linux/macOS)

B.3 Translation Layer

For cross-shell configuration:

  • ❏ Define common abstraction for aliases

  • ❏ Define common abstraction for environment variables

  • ❏ Define common abstraction for PATH modifications

  • ❏ Transpiler from abstract config to shell-specific syntax

  • ❏ Bidirectional sync between shell configs

B.4 Shell Feature Detection

Runtime detection of shell capabilities:

Feature Bash Zsh Fish Nushell PowerShell

Arrays

✓

✓

✓

✓ (tables)

✓

Associative Arrays

✓ (4.0+)

✓

✗

✓ (records)

✓ (hashtables)

Command Substitution

$()

$()

()

()

$()

Process Substitution

<()

<()

psub

✗

✗

Job Control

✓

✓

✓

Limited

✓

Programmable Completion

✓

✓

✓

✓

✓

Unicode Support

Limited

✓

✓

✓

✓

Non-Goals

The following are explicitly out of scope:

  • Shell implementation - Modshells manages configuration, not shell execution

  • Plugin system - Use native shell plugin managers instead

  • Remote shell management - Focus on local workstation configuration

  • GUI - CLI-first design; TUI may be considered later

Version Planning

Version Milestone Target

v0.1

Milestone 1 (Core Functionality)

-

v0.5

Milestone 2 (Multi-Shell Orchestration)

-

v1.0

Milestone 3 (Configuration Management)

-

v1.5

Milestone 4 (Distribution and Integration)

-

v2.0

Milestone 5 (Advanced Features)

-

Contributing

See CONTRIBUTING.md for contribution guidelines.

Priority areas for contribution:

  1. Shell-specific expertise (especially Fish, Nushell, PowerShell)

  2. Cross-platform testing (macOS, BSD, Windows via WSL)

  3. Package definitions (Homebrew, AUR, RPM, DEB)

  4. Documentation and tutorials