omnixy/scripts/README.md

Scripts Directory - Unix Philosophy Tools

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:

1. Single Purpose: Does one job well
2. Clean Output: Separates data from decoration
3. Pipeable: Output can be input to other programs
4. Scriptable: Non-interactive by default
5. 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:

1. Single Purpose: One job per script
2. Help Option: --help flag with usage info
3. Error Handling: Proper exit codes and stderr
4. Environment Variables: Respect OMNIXY_QUIET and OMNIXY_JSON
5. Documentation: Clear purpose and usage examples
6. 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.