diff --git a/README.adoc b/README.adoc index 45482a5..d5b9728 100644 --- a/README.adoc +++ b/README.adoc @@ -1,3 +1,266 @@ -= 🐚 Modular Shells: A Declarative Configuration Manager += Modshells: Modular Shell Configuration Manager +:toc: macro +:toc-title: Contents +:toclevels: 3 +:icons: font +:source-highlighter: rouge +:experimental: -(See full README structure from the previous response. This is a placeholder.) +A declarative, idempotent configuration manager for modularising shell environments. +Written in Ada for safety-critical reliability. + +toc::[] + +== Overview + +Modshells transforms monolithic shell configuration files (`.bashrc`, `.zshrc`, etc.) into a modular directory structure. Instead of maintaining a single, sprawling configuration file, Modshells organises configurations into logical categories that are automatically sourced. + +=== The Problem + +Traditional shell configuration becomes unwieldy: + +* Single files grow to hundreds of lines +* Related configurations scattered throughout +* Difficult to share configurations across shells +* No clear separation of concerns +* Risky manual editing of critical dotfiles + +=== The Solution + +Modshells creates a standardised modular structure: + +[source] +---- +~/.config/nushell/modshells/ +├── core/ # Essential shell settings, prompts, paths +├── tools/ # Tool-specific configs (git, fzf, starship) +├── misc/ # Miscellaneous aliases and functions +├── os/ # OS-specific configurations +└── ui/ # Visual customisations, themes +---- + +Each directory contains shell-agnostic or shell-specific configuration snippets that are automatically sourced in order. + +== Features + +=== Multi-Shell Support + +Modshells detects and manages configurations for ten shells: + +[cols="1,1,1"] +|=== +| Shell | Status | Config File + +| Bash | ✓ Supported | `.bashrc` +| Zsh | ✓ Supported | `.zshrc` +| Fish | ✓ Supported | `config.fish` +| Nushell | ✓ Primary | `config.nu` +| Ion | ✓ Supported | `initrc` +| Oils (OSH/YSH) | ✓ Supported | `.oshrc` +| Tcsh | ✓ Supported | `.tcshrc` +| Ksh | ✓ Supported | `.kshrc` +| Dash | ◐ Limited | `ENV` file +| PowerShell | ✓ Supported | `profile.ps1` +|=== + +=== Idempotent Operations + +All Modshells operations are idempotent: + +* Running the tool multiple times produces the same result +* Existing configurations are never destroyed +* Automatic backup before any modification +* Signature-based detection of already-modularised shells + +=== Safety-First Design + +Built in Ada for maximum reliability: + +* Strong static typing catches errors at compile time +* Exception handling ensures graceful failure +* No unsafe memory operations +* Deterministic behaviour + +== Architecture + +=== Package Structure + +[source] +---- +src/ +├── main/ +│ └── modshells.adb # Entry point +├── config_store/ +│ ├── config_store.ads # Configuration path interface +│ └── config_store.adb # Environment & path resolution +└── shell_manager/ + ├── shell_manager.ads # Shell operations interface + └── shell_manager.adb # Detection, creation, modularisation +---- + +=== Core Components + +`Config_Store`:: Resolves the modshells root path from `MODSHELLS_CONFIG_PATH` environment variable or defaults to `~/.config/nushell/modshells` + +`Shell_Manager`:: Handles shell detection, directory creation, modularisation checking, and configuration injection + +=== Signature-Based Idempotency + +Modshells uses a signature comment to detect previously modularised configurations: + +[source,bash] +---- +# MODSHELLS_START - DO NOT REMOVE THIS LINE +# ... sourcing logic ... +# MODSHELLS_END +---- + +This enables safe re-execution without duplicate injections. + +== Installation + +=== Prerequisites + +* GNAT (Ada compiler) - typically via `gnat` or `gcc-ada` package +* GPRBuild (GNAT project builder) + +=== Building from Source + +[source,bash] +---- +# Clone the repository +git clone https://github.com/hyperpolymath/modshells.git +cd modshells + +# Build with GPRBuild +gprbuild -p -j0 modshells.gpr + +# Binary is in bin/ +./bin/modshells +---- + +=== Package Managers + +[source,bash] +---- +# Guix (primary) +guix install modshells + +# Nix (alternative) +nix profile install github:hyperpolymath/modshells +---- + +== Usage + +=== Basic Initialisation + +[source,bash] +---- +# Initialise modular structure in default location +modshells + +# Use custom configuration path +export MODSHELLS_CONFIG_PATH="$HOME/.config/shells/modular" +modshells +---- + +=== Directory Structure + +After initialisation, populate directories with configuration snippets: + +[source,bash] +---- +# Add a tool configuration +echo 'alias g="git"' > ~/.config/nushell/modshells/tools/git.sh + +# Add OS-specific config +echo 'export BROWSER=firefox' > ~/.config/nushell/modshells/os/linux.sh +---- + +Files are sourced alphabetically. Use numeric prefixes for ordering: + +[source] +---- +core/ +├── 00-path.sh +├── 10-prompt.sh +└── 20-history.sh +---- + +== Configuration + +=== Environment Variables + +`MODSHELLS_CONFIG_PATH`:: Override default configuration root directory. Default: `~/.config/nushell/modshells` + +=== Modular Categories + +[cols="1,3"] +|=== +| Directory | Purpose + +| `core/` +| Essential shell settings: PATH modifications, prompt configuration, history settings, shell options + +| `tools/` +| Tool integrations: git aliases, fzf configuration, starship prompt, direnv, asdf + +| `misc/` +| General aliases, utility functions, one-off customisations + +| `os/` +| OS-specific configurations: Linux vs macOS differences, distro-specific settings + +| `ui/` +| Visual customisations: colours, themes, terminal-specific settings +|=== + +== Development Status + +Current version: **v0.0 (Alpha)** + +=== Implemented + +* [x] Core Ada package structure +* [x] Idempotent directory creation +* [x] Configuration path resolution +* [x] Environment variable support +* [x] Shell type enumeration (10 shells) +* [x] Signature-based modularisation check +* [x] GNAT project build configuration +* [x] CI/CD pipeline (GitHub Actions) + +=== In Progress + +* [ ] Actual shell detection (currently stubbed) +* [ ] Configuration file backup +* [ ] Source injection logic +* [ ] Shell-specific sourcing syntax + +See link:ROADMAP.adoc[ROADMAP.adoc] for detailed development plans. + +== Contributing + +Contributions welcome. See link:CONTRIBUTING.md[CONTRIBUTING.md] for guidelines. + +This project follows the Rhodium Standard Repository (RSR) conventions. + +=== Language Policy + +This project adheres to the Hyperpolymath Standard: + +* **Ada** for core application logic +* **Nushell** for automation scripts +* **Bash/POSIX** for git hooks only + +See `.claude/CLAUDE.md` for complete language policy. + +== License + +SPDX-License-Identifier: `AGPL-3.0-or-later OR MIT` + +Dual-licensed under GNU Affero General Public License v3.0 or later, or MIT License. See link:LICENSE.txt[LICENSE.txt] for details. + +== Citation + +For academic use, see link:docs/CITATIONS.adoc[CITATIONS.adoc] for BibTeX, Harvard, OSCOLA, MLA, and APA 7 formats. diff --git a/ROADMAP.adoc b/ROADMAP.adoc new file mode 100644 index 0000000..59599c2 --- /dev/null +++ b/ROADMAP.adoc @@ -0,0 +1,265 @@ += Modshells Development Roadmap +:toc: macro +:toc-title: Contents +:toclevels: 2 +:icons: font + +Development roadmap for Modshells, the modular shell configuration manager. + +toc::[] + +== Current State: v0.0 (Alpha) + +=== What Exists + +[cols="1,2,1"] +|=== +| 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 ` - Create new snippet +* [ ] `modshells list` - List all snippets by category +* [ ] `modshells enable/disable ` - 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: Advanced Features + +=== 5.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) + +== 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 + +[cols="1,2,1"] +|=== +| 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 link:CONTRIBUTING.md[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