The scripts/ directory contains focused, composable utilities that follow the Unix philosophy of "do one thing and do it well." These tools are designed to be scriptable, pipeable, and work together to accomplish complex tasks.

Unix Philosophy Implementation

Each script in this directory follows these principles:

Single Purpose: Does one job well
Clean Output: Separates data from decoration
Pipeable: Output can be input to other programs
Scriptable: Non-interactive by default
Composable: Works with other tools

Core System Tools

`omnixy-check-system`

Purpose: System requirements validation What it does:

Verifies NixOS installation
Checks user permissions
Validates system prerequisites

Usage:

# Check everything
./omnixy-check-system

# Check only NixOS
./omnixy-check-system --nixos-only

# Check permissions only
./omnixy-check-system --permissions-only

# Silent check for scripting
./omnixy-check-system --quiet

# JSON output
OMNIXY_JSON=1 ./omnixy-check-system

Exit Codes:

0: All checks passed
1: Critical failure (not NixOS, etc.)

Output Modes:

Default: Human-readable status
--quiet: No output, just exit codes
--json: Machine-readable JSON

`omnixy-backup-config`

Purpose: Configuration backup management What it does:

Creates timestamped backups of /etc/nixos
Outputs backup location for scripting
Handles non-existent configurations gracefully

Usage:

# Default backup with timestamp
backup_path=$(./omnixy-backup-config)

# Specify backup location
./omnixy-backup-config /custom/backup/path

# Get help
./omnixy-backup-config --help

Output:

Prints backup directory path to stdout
Can be captured and used by other scripts

`omnixy-install-files`

Purpose: File installation management What it does:

Copies configuration files to destination
Sets proper permissions
Handles directory creation

Usage:

# Install from current directory to /etc/nixos
./omnixy-install-files

# Specify source and destination
./omnixy-install-files /path/to/source /path/to/dest

# Get help
./omnixy-install-files --help

Features:

Automatic permission setting
Directory creation
Error handling

`omnixy-configure-user`

Purpose: User configuration management What it does:

Updates system configuration with username
Modifies both system and home configurations
Validates username format

Usage:

# Interactive mode (prompts for username)
username=$(./omnixy-configure-user)

# Non-interactive mode
./omnixy-configure-user alice

# Specify configuration files
./omnixy-configure-user alice /etc/nixos/configuration.nix /etc/nixos/home.nix

# Get help
./omnixy-configure-user --help

Validation:

Username must start with letter
Can contain letters, numbers, underscore, dash
Outputs the configured username

`omnixy-build-system`

Purpose: System building and switching What it does:

Builds NixOS configuration
Switches to new configuration
Supports dry-run testing

Usage:

# Build and switch system
./omnixy-build-system

# Build specific configuration
./omnixy-build-system /path/to/config custom-config

# Dry run (test only)
./omnixy-build-system --dry-run

# Get help
./omnixy-build-system --help

Modes:

Default: Build and switch to configuration
--dry-run: Test build without switching
Quiet mode: Minimal output for scripting

Tool Composition Examples

These tools are designed to work together:

Complete Installation Pipeline

#!/bin/bash
# Automated OmniXY installation

# Check system prerequisites
./scripts/omnixy-check-system || exit 1

# Backup existing configuration
backup_path=$(./scripts/omnixy-backup-config)
echo "Backup created: $backup_path"

# Install new configuration
./scripts/omnixy-install-files

# Configure user
username=$(./scripts/omnixy-configure-user "$USER")
echo "Configured for user: $username"

# Test build first
./scripts/omnixy-build-system --dry-run
echo "Configuration test passed"

# Apply changes
./scripts/omnixy-build-system
echo "System updated successfully"

Backup and Restore Workflow

#!/bin/bash
# Backup current config and test new one

# Create backup
backup=$(./scripts/omnixy-backup-config)

# Install new config
./scripts/omnixy-install-files /path/to/new/config

# Test new config
if ! ./scripts/omnixy-build-system --dry-run; then
    echo "New config failed, restoring backup"
    ./scripts/omnixy-install-files "$backup" /etc/nixos
    exit 1
fi

echo "New configuration validated"

Environment Variables

These tools respect the following environment variables:

`OMNIXY_QUIET`

When set to 1, tools produce minimal output suitable for scripting:

export OMNIXY_QUIET=1
./scripts/omnixy-check-system  # No output, just exit code

`OMNIXY_JSON`

When set to 1, tools output JSON where applicable:

export OMNIXY_JSON=1
./scripts/omnixy-check-system  # JSON status output

Integration with Main Installer

The main install-simple.sh script uses these tools:

# From install-simple.sh
scripts/omnixy-check-system
backup_path=$(scripts/omnixy-backup-config)
scripts/omnixy-install-files
username=$(scripts/omnixy-configure-user "$username")
scripts/omnixy-build-system --dry-run  # if dry run mode
scripts/omnixy-build-system           # actual installation

Error Handling

All scripts follow consistent error handling:

Exit code 0 for success
Exit code 1 for failures
Error messages to stderr
Data output to stdout

Example error handling:

if ! ./scripts/omnixy-check-system --quiet; then
    echo "System check failed" >&2
    exit 1
fi

Adding New Tools

When adding new Unix philosophy tools:

Single Purpose: One job per script
Help Option: --help flag with usage info
Error Handling: Proper exit codes and stderr
Environment Variables: Respect OMNIXY_QUIET and OMNIXY_JSON
Documentation: Clear purpose and usage examples
Testing: Verify with various inputs and edge cases

Design Principles

These tools embody:

Composability: Tools work together through pipes and command chaining

Reliability: Consistent interfaces and error handling

Scriptability: Non-interactive operation with clear outputs

Maintainability: Simple, focused implementations

Testability: Each tool can be tested in isolation

This approach makes the OmniXY installation and management system both powerful and maintainable while following time-tested Unix design principles.