Ashell-Dotfiles

Production-grade dotfiles and DevOps automation for a-Shell on iOS.

A comprehensive, tested, and maintainable setup for configuring a-Shell as a functional DevOps environment on iPad and iPhone, with support for Git, Node.js, Python, and essential CLI tools.

Features

✅ Cross-platform package manager detection (apk, apt, brew, yum, dnf) ✅ Multi-shell support (bash, zsh, fish) with auto-detection ✅ Idempotent installation (safe to run multiple times) ✅ Comprehensive error handling with recovery paths ✅ Dry-run mode for safe preview before execution ✅ Configuration backups before any modifications ✅ Verified installations with post-install checks ✅ Color-coded logging with verbose/debug modes ✅ iOS a-Shell optimized (respects sandbox constraints) ✅ Production-grade shell scripting (ShellCheck validated)

Architecture

ashell-dotfiles/
├── install.sh              # Main bootstrap script (production-grade)
├── setup.sh                # a-Shell environment initialization
├── README.md               # This file
├── .shellcheckrc           # ShellCheck configuration
└── tests/
    ├── install.sh.test     # Test suite for install.sh
    └── setup.sh.test       # Test suite for setup.sh

Design Principles

Deterministic State: Scripts idempotently reach target state regardless of re-runs
Explicit Error Handling: No silent failures; all errors surface immediately
iOS Compatibility: Respects a-Shell sandbox restrictions (no background jobs, no network daemon)
Production Safety: Backups created before modifications; recovery paths documented
Maintainability: Strict typing, clear variable names, comprehensive logging

Requirements

a-Shell (iOS)

a-Shell v1.14+ from App Store
iOS 14.0 or later
~100MB free storage

Linux/macOS

Bash 4.0+
Git 2.0+
One of: apk (Alpine), apt (Debian/Ubuntu), brew (macOS), yum (RHEL), dnf (Fedora)

Installation

Quick Start

# Download and execute bootstrap script
curl -fsSL https://raw.githubusercontent.com/themerchantstoretms-dev/Ashell-Dotfiles/main/install.sh | bash

Explicit Download & Verification

# Clone or download repository
git clone https://github.com/themerchantstoretms-dev/Ashell-Dotfiles.git
cd Ashell-Dotfiles

# View what will be installed (dry-run mode)
./install.sh --dry-run --verbose

# Execute installation
./install.sh --verbose

# Reload shell configuration
source ~/.bashrc   # for bash
source ~/.zshrc    # for zsh
source ~/.config/fish/config.fish  # for fish

Installation Options

./install.sh [OPTIONS]

OPTIONS:
  --dry-run          Preview changes without modifying filesystem
  --verbose, -v      Show detailed execution logs
  --shell=SHELL      Target shell (bash, zsh, fish). Auto-detected by default.
  --help, -h         Display usage information

What Gets Installed

Tool	Purpose	Package Manager
git	Version control	apk/apt/brew/yum/dnf
curl	HTTP client	apk/apt/brew/yum/dnf
python3	Python runtime	apk/apt/brew/yum/dnf
nodejs	Node.js runtime	apk/apt/brew/yum/dnf
fzf	Fuzzy finder (interactive menus)	apk/apt/brew/yum/dnf
zoxide	Quick directory navigation	apk/apt/brew/yum/dnf
peco	Interactive filtering tool	apk/apt/brew/yum/dnf
dialog	CLI dialog menus	apk/apt/brew/yum/dnf

Configuration Created

Path	Purpose	Can Modify
`~/.ashell/menu.sh`	Interactive command palette	Yes (will not overwrite)
`~/.ashell/helpers.sh`	DevOps helper functions	Yes (will not overwrite)
`~/.bashrc` / `~/.zshrc` / `~/.config/fish/config.fish`	Shell aliases and sourcing	Yes (backup created first)

Usage

Command Palette

After installation, the / command triggers the interactive menu:

Output:

===================================
   a-Shell DevOps Hub Menu
===================================

Choose an action:
  1) Open Repository
  2) List Issues
  3) Create Pull Request
  4) Commit Changes
  5) Exit

Enter your choice (1-5):

Helper Functions

Available in all shells via ~/.ashell/helpers.sh:

# Open a repository
ashell_open_repo <repo-url-or-path>

# List issues (placeholder for future implementation)
ashell_list_issues

# Create pull request (placeholder for future implementation)
ashell_create_pr

Examples

# Navigate quickly
z my_project  # via zoxide

# Find files interactively
fzf

# Check Git status with enhanced view
git status

# Run the DevOps menu
/

# Source custom helpers
source ~/.ashell/helpers.sh
ashell_open_repo ~/my-repo

Configuration

Shell-Specific Configuration

For Bash (~/.bashrc):

# a-Shell DevOps Hub Configuration
alias /='bash ~/.ashell/menu.sh'
source ~/.ashell/helpers.sh

For Zsh (~/.zshrc):

# a-Shell DevOps Hub Configuration
alias /='bash ~/.ashell/menu.sh'
source ~/.ashell/helpers.sh

For Fish (~/.config/fish/config.fish):

# a-Shell DevOps Hub Configuration
alias / 'bash ~/.ashell/menu.sh'
source ~/.ashell/helpers.sh

Customization

Edit ~/.ashell/menu.sh to add custom menu options:

#!/bin/bash

echo "==================================="
echo "   a-Shell DevOps Hub Menu"
echo "==================================="
echo ""
echo "Choose an action:"
echo "  1) Open Repository"
echo "  2) List Issues"
echo "  6) Custom Action"  # Add your custom option
echo ""
read -p "Enter your choice: " choice

case $choice in
  1) echo "Opening Repository..." ;;
  2) echo "Listing Issues..." ;;
  6) your_custom_function ;;  # Call your function
  *) echo "Invalid choice." ; exit 1 ;;
esac

Edit ~/.ashell/helpers.sh to add custom functions:

#!/bin/bash

# Your custom DevOps functions
my_custom_command() {
  echo "Executing custom command..."
  # Your logic here
}

Troubleshooting

Installation Fails on Package Installation

Problem: One or more packages fail to install.

Solution:

# Run with verbose output to see exact error
./install.sh --verbose

# Try manual installation for specific package
# Example for brew on macOS:
brew install <package-name>

# Non-critical packages (fzf, zoxide, peco, dialog) can be skipped
# The script will continue even if these fail

Shell Configuration Not Applied

Problem: Changes to ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish not taking effect.

Solution:

# Reload shell configuration
source ~/.bashrc   # for bash
source ~/.zshrc    # for zsh
source ~/.config/fish/config.fish  # for fish

# Or restart the shell entirely
bash    # or zsh, or fish

Menu Command (/) Not Working

Problem: / command returns "command not found"

Solution:

# Verify alias was created
alias | grep "^alias /="

# If missing, source the shell config manually
source ~/.bashrc   # or ~/.zshrc for zsh

# If still missing, verify menu.sh exists
ls -la ~/.ashell/menu.sh

# If missing, re-run install script
./install.sh

Package Manager Not Detected

Problem: "No supported package manager found"

Solution:

# Install your system's package manager first, then re-run
# Examples:
# - Alpine: apk (should already exist)
# - Debian/Ubuntu: apt-get
# - macOS: brew (install from https://brew.sh)
# - RHEL/CentOS: yum or dnf

# After installing PM, re-run:
./install.sh --verbose

Dry-Run Shows Errors

Problem: --dry-run displays error messages but makes no changes.

Solution:

# This is expected behavior—dry-run validates without modifying
# Review the output for issues, then run without --dry-run
./install.sh --verbose

# Check backups if needed
ls -la ~/.dotfiles_backup.*

On iOS a-Shell Specifically

Problem: dialog or peco not available in a-Shell iOS.

Solution:

# a-Shell iOS has limited tool availability
# These packages may not install on iOS
# The install script will skip them with a warning (non-critical)
# Functionality will still work with standard tools (fzf, zoxide, etc.)

iOS Constraints & Workarounds

a-Shell iOS Sandboxing

a-Shell runs within iOS app sandbox with specific constraints:

Constraint	Impact	Workaround
No persistent background jobs	Can't run daemons (Redis, nginx, etc.)	Use cloud services or macOS/Linux for servers
Network restricted by iOS	Limited outbound connections	Use SSH for remote access; rely on curl/wget for APIs
No file watching (inotify)	Can't watch directories for changes	Manual triggers or cloud-based file sync
Processes terminate on app close	Long jobs interrupted	Keep app active or use remote execution
Limited system access	Can't modify OS-level configs	Configure within a-Shell sandbox only

Recommended iOS Workflows

Code Review & Git Operations

git clone <repo>
git checkout -b feature/my-feature
git status
git add .
git commit -m "message"
git push origin feature/my-feature

Remote Server Management

# SSH into remote servers
ssh user@remote-host

# Copy files
scp local-file user@remote-host:/path/

# Monitor logs
ssh user@remote-host "tail -f /var/log/app.log"

Script Development & Testing

# Write and test scripts locally
nano my-script.sh
chmod +x my-script.sh
./my-script.sh

# Push to git when ready
git add my-script.sh
git commit -m "Add my-script"
git push

Quick API Testing

curl -X GET https://api.example.com/endpoint
curl -X POST -d '{"key":"value"}' https://api.example.com/endpoint

# With jq for JSON parsing
curl https://api.example.com/data | jq '.results[]'

Contributing

We welcome contributions! Follow these guidelines:

Before Submitting

Run ShellCheck validation:
```
shellcheck install.sh setup.sh
```

Run test suite:

bats tests/install.sh.test
bats tests/setup.sh.test

Test on your platform:

./install.sh --dry-run --verbose
./install.sh --verbose
source ~/.bashrc  # or ~/.zshrc
/  # Test menu works

Submission Process

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Make changes and test thoroughly
Commit with clear messages: git commit -m "feat: Add X functionality"
Push to your fork: git push origin feature/my-feature
Open a Pull Request with description of changes

Code Standards

Bash: ShellCheck clean, set -euo pipefail, quoted variables
Functions: Documented with purpose, arguments, return values
Variables: Explicit names, no abbreviations except obvious (i, n in loops)
Logging: Use log_info(), log_warn(), log_error() functions
Comments: Explain "why," not "what" (code is self-documenting)

Testing

Manual Testing

# Dry-run mode (no changes)
./install.sh --dry-run --verbose

# Install with verbose output
./install.sh --verbose

# Test after installation
/ # Should show menu
fzf # Should work
zoxide # Should work

Automated Testing (When Available)

# Run test suite
bats tests/*.test

# Run ShellCheck
shellcheck install.sh setup.sh

Recovery & Uninstallation

Restore Backed-Up Configuration

After installation, a timestamped backup is created:

# List available backups
ls -la ~/.dotfiles_backup.*

# Restore specific backup
cp ~/.dotfiles_backup.1234567890/.bashrc ~/.bashrc
cp ~/.dotfiles_backup.1234567890/.zshrc ~/.zshrc

# Reload shell
source ~/.bashrc

Remove a-Shell Configuration (Manual Uninstall)

# Remove menu and helpers
rm -rf ~/.ashell

# Remove aliases and sourcing from shell RC files
# Edit ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish
# Remove lines:
#   alias /='bash ~/.ashell/menu.sh'
#   source ~/.ashell/helpers.sh

# Reload shell
source ~/.bashrc

FAQ

Q: Can I run servers (Redis, PostgreSQL, etc.) in a-Shell? A: No. iOS app sandbox prevents long-lived background processes. Use cloud services (Redis Cloud, AWS RDS, etc.) or run servers on a separate Linux/macOS machine.

Q: Can I schedule cron jobs in a-Shell? A: Not persistently. a-Shell runs only while the app is active. Use GitHub Actions, cloud schedulers, or a separate Linux server for scheduled tasks.

Q: Is my data secure in a-Shell? A: a-Shell runs in iOS app sandbox, so your data is isolated from other apps. But the app itself is not open-source for the iOS version, so assume reasonable but not absolute security. Don't store highly sensitive credentials; use environment variables instead.

Q: How do I access my code from other devices? A: Use Git (GitHub, GitLab, etc.) to sync code. Use iCloud Drive, Dropbox, or OneDrive for files. Use SSH to connect to remote servers for direct file transfer.

Q: Can I edit files in a-Shell and sync to my Mac/PC? A: Yes. Use Git for code, or use cloud storage (iCloud Drive, Dropbox) for file syncing.

Resources

a-Shell GitHub: https://github.com/holzschu/a-shell
a-Shell Documentation: https://github.com/holzschu/a-shell/wiki
ShellCheck: https://www.shellcheck.net/
Bash Best Practices: https://www.projectrules.ai/rules/bash
Git Documentation: https://git-scm.com/doc

License

This repository is provided as-is for educational and development purposes.

Support

For issues, questions, or feature requests:

Check Troubleshooting section above
Review existing GitHub Issues: https://github.com/themerchantstoretms-dev/Ashell-Dotfiles/issues
Open a new issue with:
- Your system (a-Shell iOS / Linux / macOS)
- Output from ./install.sh --verbose
- Steps to reproduce
- Expected vs. actual behavior

Last Updated: 2026-05-26 Maintainer: themerchantstoretms-dev

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.devcontainer		.devcontainer
Dev ops		Dev ops
tests		tests
.chezmoi.toml.tmpl		.chezmoi.toml.tmpl
.shellcheckrc		.shellcheckrc
README.md		README.md
bootstrap.py		bootstrap.py
install.sh		install.sh
setup.sh		setup.sh

Folders and files

Latest commit

History

Repository files navigation

Ashell-Dotfiles

Table of Contents

Features

Architecture

Design Principles

Requirements

a-Shell (iOS)

Linux/macOS

Installation

Quick Start

Explicit Download & Verification

Installation Options

What Gets Installed

Configuration Created

Usage

Command Palette

Helper Functions

Examples

Configuration

Shell-Specific Configuration

Customization

Troubleshooting

Installation Fails on Package Installation

Shell Configuration Not Applied

Menu Command (/) Not Working

Package Manager Not Detected

Dry-Run Shows Errors

On iOS a-Shell Specifically

iOS Constraints & Workarounds

a-Shell iOS Sandboxing

Recommended iOS Workflows

Contributing

Before Submitting

Submission Process

Code Standards

Testing

Manual Testing

Automated Testing (When Available)

Recovery & Uninstallation

Restore Backed-Up Configuration

Remove a-Shell Configuration (Manual Uninstall)

FAQ

Resources

License

Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages