documentation

scripts/README.md

@@ -0,0 +1,277 @@
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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
+```bash
+#!/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
+```bash
+#!/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:
+```bash
+export OMNIXY_QUIET=1
+./scripts/omnixy-check-system  # No output, just exit code
+```
+
+### `OMNIXY_JSON`
+When set to `1`, tools output JSON where applicable:
+```bash
+export OMNIXY_JSON=1
+./scripts/omnixy-check-system  # JSON status output
+```
+
+## Integration with Main Installer
+
+The main `install-simple.sh` script uses these tools:
+
+```bash
+# 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:
+```bash
+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.

scripts/omnixy-backup-config

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Unix-style config backup - does one thing well
+set -e
+
+backup_config() {
+    local backup_dir="${1:-}"
+    local timestamp=$(date +%Y%m%d-%H%M%S)
+
+    # Default backup location
+    if [[ -z "$backup_dir" ]]; then
+        backup_dir="/etc/nixos.backup.$timestamp"
+    fi
+
+    # Only backup if source exists
+    if [[ ! -d /etc/nixos ]]; then
+        [[ "${OMNIXY_QUIET:-}" != "1" ]] && echo "No existing configuration to backup"
+        exit 0
+    fi
+
+    # Create backup
+    sudo cp -r /etc/nixos "$backup_dir"
+
+    # Output backup location for piping/scripting
+    echo "$backup_dir"
+}
+
+main() {
+    case "${1:-}" in
+        --help|-h)
+            echo "Usage: omnixy-backup-config [backup-directory]"
+            echo "Backs up /etc/nixos to specified directory (or timestamped default)"
+            exit 0
+            ;;
+        *)
+            backup_config "$1"
+            ;;
+    esac
+}
+
+main "$@"

scripts/omnixy-build-system

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Unix-style system builder - does one thing well
+set -e
+
+build_system() {
+    local flake_path="${1:-/etc/nixos}"
+    local config_name="${2:-omnixy}"
+
+    cd "$flake_path"
+
+    if [[ "${OMNIXY_QUIET:-}" == "1" ]]; then
+        sudo nixos-rebuild switch --flake ".#$config_name" >/dev/null 2>&1
+    else
+        echo "Building system configuration..."
+        sudo nixos-rebuild switch --flake ".#$config_name"
+        echo "System build complete"
+    fi
+}
+
+main() {
+    case "${1:-}" in
+        --help|-h)
+            echo "Usage: omnixy-build-system [flake-path] [config-name]"
+            echo "Builds and switches to NixOS configuration"
+            echo "Default: /etc/nixos omnixy"
+            exit 0
+            ;;
+        --dry-run|-n)
+            shift
+            cd "${1:-/etc/nixos}"
+            nixos-rebuild build --flake ".#${2:-omnixy}"
+            ;;
+        *)
+            build_system "$1" "$2"
+            ;;
+    esac
+}
+
+main "$@"

scripts/omnixy-check-system

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Unix-style system checker - does one thing well
+set -e
+
+# Check if running on NixOS
+check_nixos() {
+    [ -f /etc/NIXOS ] || {
+        echo "Not running on NixOS" >&2
+        exit 1
+    }
+}
+
+# Check permissions (warn if root, but don't block)
+check_permissions() {
+    if [ "$EUID" -eq 0 ]; then
+        echo "Warning: Running as root is not recommended" >&2
+        return 1
+    fi
+    return 0
+}
+
+# Main check
+main() {
+    case "${1:-}" in
+        --nixos-only)
+            check_nixos
+            ;;
+        --permissions-only)
+            check_permissions
+            ;;
+        --quiet|-q)
+            check_nixos >/dev/null 2>&1
+            check_permissions >/dev/null 2>&1
+            ;;
+        *)
+            check_nixos
+            check_permissions || true  # Don't exit on root warning
+            ;;
+    esac
+
+    # Output status for scripting
+    if [[ "${OMNIXY_JSON:-}" == "1" ]]; then
+        echo '{"nixos": true, "root": '$([ "$EUID" -eq 0 ] && echo "true" || echo "false")'}'
+    fi
+}
+
+main "$@"

scripts/omnixy-configure-user

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Unix-style user configuration - does one thing well
+set -e
+
+configure_user() {
+    local username="${1:-}"
+    local config_file="${2:-/etc/nixos/configuration.nix}"
+    local home_file="${3:-/etc/nixos/home.nix}"
+
+    # Get username if not provided
+    if [[ -z "$username" ]]; then
+        if [[ "${OMNIXY_QUIET:-}" == "1" ]]; then
+            echo "Username required in quiet mode" >&2
+            exit 1
+        fi
+        read -p "Username: " username
+    fi
+
+    # Validate username
+    if [[ ! "$username" =~ ^[a-zA-Z][a-zA-Z0-9_-]*$ ]]; then
+        echo "Invalid username: $username" >&2
+        exit 1
+    fi
+
+    # Update configuration files
+    if [[ -f "$config_file" ]]; then
+        sudo sed -i "s/user = \"user\"/user = \"$username\"/" "$config_file"
+        [[ "${OMNIXY_QUIET:-}" != "1" ]] && echo "Updated main configuration"
+    fi
+
+    if [[ -f "$home_file" ]]; then
+        sudo sed -i "s/home.username = \"user\"/home.username = \"$username\"/" "$home_file" 2>/dev/null || true
+        sudo sed -i "s|home.homeDirectory = \"/home/user\"|home.homeDirectory = \"/home/$username\"|" "$home_file" 2>/dev/null || true
+        [[ "${OMNIXY_QUIET:-}" != "1" ]] && echo "Updated home configuration"
+    fi
+
+    # Output username for scripting
+    echo "$username"
+}
+
+main() {
+    case "${1:-}" in
+        --help|-h)
+            echo "Usage: omnixy-configure-user [username] [config-file] [home-file]"
+            echo "Updates configuration files with specified username"
+            echo "Prompts for username if not provided (unless --quiet)"
+            exit 0
+            ;;
+        *)
+            configure_user "$1" "$2" "$3"
+            ;;
+    esac
+}
+
+main "$@"

scripts/omnixy-install-files

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Unix-style file installer - does one thing well
+set -e
+
+install_files() {
+    local source_dir="${1:-.}"
+    local dest_dir="${2:-/etc/nixos}"
+
+    # Validate source
+    [[ -d "$source_dir" ]] || {
+        echo "Source directory '$source_dir' not found" >&2
+        exit 1
+    }
+
+    # Create destination
+    sudo mkdir -p "$dest_dir"
+
+    # Copy files
+    sudo cp -r "$source_dir"/* "$dest_dir"/
+
+    # Set proper permissions
+    sudo chown -R root:root "$dest_dir"
+    sudo chmod 755 "$dest_dir"
+
+    [[ "${OMNIXY_QUIET:-}" != "1" ]] && echo "Files installed to $dest_dir"
+}
+
+main() {
+    case "${1:-}" in
+        --help|-h)
+            echo "Usage: omnixy-install-files [source-dir] [dest-dir]"
+            echo "Copies configuration files from source to destination"
+            echo "Default: current directory to /etc/nixos"
+            exit 0
+            ;;
+        *)
+            install_files "$1" "$2"
+            ;;
+    esac
+}
+
+main "$@"