documentation

packages/README.md

@@ -0,0 +1,251 @@
+# Packages Directory - Custom Nix Packages
+
+The `packages/` directory contains custom Nix package definitions for OmniXY-specific tools and utilities. These packages are built and distributed through the Nix package manager as part of the OmniXY system.
+
+## Package Architecture
+
+Each package follows the standard Nix packaging format:
+```nix
+{ pkgs, lib, ... }:
+pkgs.stdenv.mkDerivation rec {
+  pname = "package-name";
+  version = "1.0.0";
+
+  # Package definition
+  # ...
+
+  meta = with lib; {
+    description = "Package description";
+    license = licenses.mit;
+    platforms = platforms.linux;
+  };
+}
+```
+
+## Current Packages
+
+### `scripts.nix`
+**Purpose**: OmniXY utility scripts package
+**What it contains**: All the management and utility scripts for OmniXY system
+
+**Generated Scripts**:
+
+#### System Management
+- `omnixy`: Main command interface with `--quiet` and `--json` modes
+- `omnixy-update`: System and flake updates with progress indication
+- `omnixy-clean`: Garbage collection and store optimization
+- `omnixy-rebuild`: Wrapper for `nixos-rebuild switch`
+
+#### Theme Management
+- `omnixy-theme-set`: Set system theme with validation
+- `omnixy-theme-list`: List available themes (plain/JSON output)
+- `omnixy-theme-get`: Get current theme (scriptable output)
+
+#### Package Management
+- `omnixy-search`: Search Nix packages
+- `omnixy-install`: Package installation guide
+
+#### Development Tools
+- `omnixy-dev-shell`: Language-specific development shells
+  - Supports: rust, go, python, node/js, c/cpp
+
+#### Utilities
+- `omnixy-screenshot`: Screenshot tool with region/window/full modes
+- `omnixy-info`: System information with JSON/quiet modes
+- `omnixy-help`: Comprehensive help system
+
+**Build Process**:
+1. Creates all scripts in `installPhase`
+2. Sets executable permissions
+3. Patches interpreter paths
+4. Validates script syntax
+
+**Dependencies**:
+- `bash`: Shell interpreter
+- `coreutils`: Basic Unix utilities
+- `gnugrep`, `gnused`, `gawk`: Text processing
+- `jq`: JSON processing
+- `curl`, `wget`: Network utilities
+- `git`: Version control
+- `fzf`, `ripgrep`: Search tools
+
+### `plymouth-theme.nix` (Commented Out)
+**Purpose**: Plymouth boot theme package
+**Status**: Disabled until fully implemented
+**What it would contain**: Custom boot splash theme for OmniXY
+
+## Package Integration
+
+### Flake Integration
+Packages are exported in `flake.nix`:
+```nix
+packages.${system} = {
+  omnixy-scripts = pkgs.callPackage ./packages/scripts.nix {};
+  # Additional packages...
+};
+```
+
+### System Installation
+Scripts package is installed system-wide in the main configuration, making all utilities available in PATH.
+
+### Development Access
+Packages can be built individually for testing:
+```bash
+# Build scripts package
+nix build .#omnixy-scripts
+
+# Test individual script
+./result/bin/omnixy --help
+```
+
+## Script Features
+
+### Unix Philosophy Compliance
+All scripts follow Unix principles:
+
+**Clean Output Separation**:
+```bash
+# Human-readable (default)
+omnixy info
+
+# Machine-readable
+omnixy --json info | jq .system.version
+
+# Scriptable
+omnixy --quiet update && echo "Updated successfully"
+```
+
+**Composability**:
+```bash
+# Theme management pipeline
+current_theme=$(omnixy --quiet theme get)
+omnixy theme list --quiet | grep -v "$current_theme" | head -1 | xargs omnixy theme set
+```
+
+**Error Handling**:
+- Exit codes: 0 for success, 1 for failure
+- Errors to stderr, data to stdout
+- Graceful handling of missing files/permissions
+
+### Environment Variables
+Scripts respect global settings:
+
+- `OMNIXY_QUIET=1`: Minimal output mode
+- `OMNIXY_JSON=1`: JSON output where applicable
+
+### Theme System Integration
+Theme scripts provide complete theme management:
+- List all 11 available themes
+- Get current theme for scripting
+- Set theme with validation and rebuild
+- Support for both interactive and automated usage
+
+### Development Environment Support
+Development scripts provide:
+- Quick access to language-specific environments
+- Consistent tooling across languages
+- Integration with system configuration
+
+## Adding New Packages
+
+To add a new package:
+
+1. **Create Package File**:
+```nix
+# packages/my-tool.nix
+{ pkgs, lib, ... }:
+pkgs.stdenv.mkDerivation rec {
+  pname = "my-tool";
+  version = "1.0.0";
+
+  # Package definition
+}
+```
+
+2. **Add to Flake**:
+```nix
+# In flake.nix packages section
+my-tool = pkgs.callPackage ./packages/my-tool.nix {};
+```
+
+3. **Install in System**:
+```nix
+# In configuration or module
+environment.systemPackages = with pkgs; [
+  # ... other packages
+  my-tool
+];
+```
+
+## Package Categories
+
+### System Utilities
+Tools for managing the OmniXY system itself:
+- Configuration management
+- System updates and maintenance
+- Backup and restore operations
+
+### User Interface Tools
+Scripts for desktop and user interaction:
+- Theme management
+- Screenshot utilities
+- Information display
+
+### Development Aids
+Tools for software development:
+- Environment management
+- Build and deployment helpers
+- Debug and diagnostic tools
+
+### Integration Scripts
+Utilities for integrating with external systems:
+- Cloud services
+- Version control
+- Package repositories
+
+## Build System
+
+### Derivation Structure
+Each package is a Nix derivation with:
+- **Inputs**: Dependencies and build tools
+- **Build Process**: How to create the package
+- **Outputs**: Resulting files and executables
+- **Metadata**: Description, license, platforms
+
+### Build Phases
+For script packages:
+1. **Setup**: Prepare build environment
+2. **Install**: Create scripts and set permissions
+3. **Fixup**: Patch interpreters and validate
+4. **Package**: Create final Nix store paths
+
+### Quality Assurance
+- Syntax checking during build
+- Interpreter path patching
+- Permission validation
+- Dependency verification
+
+## Testing and Validation
+
+### Build Testing
+```bash
+# Test package builds correctly
+nix build .#omnixy-scripts
+
+# Validate all scripts are created
+ls result/bin/ | wc -l
+
+# Test script functionality
+result/bin/omnixy --help
+```
+
+### Integration Testing
+```bash
+# Test in clean environment
+nix develop --command bash -c "omnixy-info --json | jq .system"
+
+# Test cross-script integration
+nix develop --command bash -c "omnixy theme list --quiet | head -1 | xargs echo"
+```
+
+This packaging system provides a robust foundation for distributing and managing OmniXY utilities while maintaining the reproducibility and reliability of the Nix ecosystem.

packages/scripts.nix

@@ -31,34 +31,62 @@ pkgs.stdenv.mkDerivation rec {
     set -e
 
     THEME="$1"
-    AVAILABLE_THEMES="tokyo-night catppuccin gruvbox nord everforest rose-pine kanagawa"
+    AVAILABLE_THEMES="tokyo-night catppuccin gruvbox nord everforest rose-pine kanagawa catppuccin-latte matte-black osaka-jade ristretto"
 
     if [ -z "$THEME" ]; then
-      echo "Usage: omnixy-theme-set <theme>"
-      echo "Available themes: $AVAILABLE_THEMES"
+      if [[ "''${OMNIXY_QUIET:-}" == "1" ]]; then
+        exit 1
+      fi
+      echo "Usage: omnixy theme set <theme>" >&2
+      echo "Available themes: $AVAILABLE_THEMES" >&2
       exit 1
     fi
 
     if ! echo "$AVAILABLE_THEMES" | grep -qw "$THEME"; then
-      echo "Error: Unknown theme '$THEME'"
-      echo "Available themes: $AVAILABLE_THEMES"
+      if [[ "''${OMNIXY_QUIET:-}" == "1" ]]; then
+        exit 1
+      fi
+      echo "Error: Unknown theme '$THEME'" >&2
+      echo "Available themes: $AVAILABLE_THEMES" >&2
       exit 1
     fi
 
-    echo "Switching to theme: $THEME"
-
     # Update configuration
     sudo sed -i "s/currentTheme = \".*\"/currentTheme = \"$THEME\"/" /etc/nixos/configuration.nix
 
-    # Rebuild system
-    sudo nixos-rebuild switch --flake /etc/nixos#omnixy
+    if [[ "''${OMNIXY_QUIET:-}" != "1" ]]; then
+      echo "Switching to theme: $THEME"
+    fi
 
-    echo "Theme switched to $THEME successfully!"
+    # Rebuild system
+    if [[ "''${OMNIXY_QUIET:-}" == "1" ]]; then
+      sudo nixos-rebuild switch --flake /etc/nixos#omnixy >/dev/null 2>&1
+    else
+      sudo nixos-rebuild switch --flake /etc/nixos#omnixy
+      echo "Theme switched to $THEME successfully!"
+    fi
     EOF
     chmod +x $out/bin/omnixy-theme-set
 
     cat > $out/bin/omnixy-theme-list << 'EOF'
     #!/usr/bin/env bash
+
+    THEMES="tokyo-night catppuccin gruvbox nord everforest rose-pine kanagawa catppuccin-latte matte-black osaka-jade ristretto"
+
+    if [[ "''${OMNIXY_QUIET:-}" == "1" ]]; then
+      echo "$THEMES" | tr ' ' '\n'
+      exit 0
+    fi
+
+    if [[ "''${OMNIXY_JSON:-}" == "1" ]]; then
+      current=$(grep currentTheme /etc/nixos/configuration.nix 2>/dev/null | cut -d'"' -f2 || echo "tokyo-night")
+      echo '{'
+      echo '  "available": ["'$(echo "$THEMES" | sed 's/ /", "/g')'"],'
+      echo '  "current": "'$current'"'
+      echo '}'
+      exit 0
+    fi
+
     echo "Available OmniXY themes:"
     echo "========================"
     echo "  • tokyo-night (default)"
@@ -68,38 +96,70 @@ pkgs.stdenv.mkDerivation rec {
     echo "  • everforest"
     echo "  • rose-pine"
     echo "  • kanagawa"
+    echo "  • catppuccin-latte"
+    echo "  • matte-black"
+    echo "  • osaka-jade"
+    echo "  • ristretto"
     echo ""
-    echo "Current theme: $(grep currentTheme /etc/nixos/configuration.nix | cut -d'"' -f2)"
+    echo "Current theme: $(grep currentTheme /etc/nixos/configuration.nix 2>/dev/null | cut -d'"' -f2 || echo "tokyo-night")"
     echo ""
-    echo "To change theme, run: omnixy-theme-set <theme-name>"
+    echo "To change theme, run: omnixy theme set <theme-name>"
     EOF
     chmod +x $out/bin/omnixy-theme-list
 
+    # Get current theme command
+    cat > $out/bin/omnixy-theme-get << 'EOF'
+    #!/usr/bin/env bash
+    current=$(grep currentTheme /etc/nixos/configuration.nix 2>/dev/null | cut -d'"' -f2 || echo "tokyo-night")
+
+    if [[ "''${OMNIXY_JSON:-}" == "1" ]]; then
+      echo '{"current": "'$current'"}'
+    else
+      echo "$current"
+    fi
+    EOF
+    chmod +x $out/bin/omnixy-theme-get
+
     # System management
     cat > $out/bin/omnixy-update << 'EOF'
     #!/usr/bin/env bash
     set -e
 
-    echo "🔄 Updating OmniXY system..."
-    echo ""
+    if [[ "''${OMNIXY_QUIET:-}" != "1" ]]; then
+      echo "🔄 Updating OmniXY system..."
+      echo ""
+    fi
 
     # Update flake inputs
-    echo "📦 Updating flake inputs..."
+    if [[ "''${OMNIXY_QUIET:-}" != "1" ]]; then
+      echo "📦 Updating flake inputs..."
+    fi
     cd /etc/nixos
-    sudo nix flake update
+    if [[ "''${OMNIXY_QUIET:-}" == "1" ]]; then
+      sudo nix flake update >/dev/null 2>&1
+    else
+      sudo nix flake update
+    fi
 
     # Show what changed
-    echo ""
-    echo "📊 Changes:"
-    git diff flake.lock | grep -E "^\+" | head -20
+    if [[ "''${OMNIXY_QUIET:-}" != "1" ]]; then
+      echo ""
+      echo "📊 Changes:"
+      git diff flake.lock | grep -E "^\+" | head -20
+    fi
 
     # Rebuild system
-    echo ""
-    echo "🏗️  Rebuilding system..."
-    sudo nixos-rebuild switch --flake .#omnixy
-
-    echo ""
-    echo "✅ System updated successfully!"
+    if [[ "''${OMNIXY_QUIET:-}" != "1" ]]; then
+      echo ""
+      echo "🏗️  Rebuilding system..."
+    fi
+    if [[ "''${OMNIXY_QUIET:-}" == "1" ]]; then
+      sudo nixos-rebuild switch --flake .#omnixy >/dev/null 2>&1
+    else
+      sudo nixos-rebuild switch --flake .#omnixy
+      echo ""
+      echo "✅ System updated successfully!"
+    fi
     EOF
     chmod +x $out/bin/omnixy-update
 
@@ -107,29 +167,44 @@ pkgs.stdenv.mkDerivation rec {
     #!/usr/bin/env bash
     set -e
 
-    echo "🧹 Cleaning OmniXY system..."
-    echo ""
+    if [[ "''${OMNIXY_QUIET:-}" != "1" ]]; then
+      echo "🧹 Cleaning OmniXY system..."
+      echo ""
 
-    # Show current store size
-    echo "Current store size:"
-    du -sh /nix/store 2>/dev/null || echo "Unable to calculate"
-    echo ""
+      # Show current store size
+      echo "Current store size:"
+      du -sh /nix/store 2>/dev/null || echo "Unable to calculate"
+      echo ""
+    fi
 
     # Run garbage collection
-    echo "Running garbage collection..."
-    sudo nix-collect-garbage -d
+    if [[ "''${OMNIXY_QUIET:-}" != "1" ]]; then
+      echo "Running garbage collection..."
+    fi
+    if [[ "''${OMNIXY_QUIET:-}" == "1" ]]; then
+      sudo nix-collect-garbage -d >/dev/null 2>&1
+    else
+      sudo nix-collect-garbage -d
+    fi
 
     # Optimize store
-    echo "Optimizing Nix store..."
-    sudo nix-store --optimise
+    if [[ "''${OMNIXY_QUIET:-}" != "1" ]]; then
+      echo "Optimizing Nix store..."
+    fi
+    if [[ "''${OMNIXY_QUIET:-}" == "1" ]]; then
+      sudo nix-store --optimise >/dev/null 2>&1
+    else
+      sudo nix-store --optimise
+    fi
 
-    # Show new size
-    echo ""
-    echo "New store size:"
-    du -sh /nix/store 2>/dev/null || echo "Unable to calculate"
-
-    echo ""
-    echo "✅ Cleanup complete!"
+    if [[ "''${OMNIXY_QUIET:-}" != "1" ]]; then
+      # Show new size
+      echo ""
+      echo "New store size:"
+      du -sh /nix/store 2>/dev/null || echo "Unable to calculate"
+      echo ""
+      echo "✅ Cleanup complete!"
+    fi
     EOF
     chmod +x $out/bin/omnixy-clean
 
@@ -251,31 +326,71 @@ pkgs.stdenv.mkDerivation rec {
     cat > $out/bin/omnixy-info << 'EOF'
     #!/usr/bin/env bash
 
+    # Gather data once
+    VERSION=$(nixos-version)
+    KERNEL=$(uname -r)
+    THEME=$(grep currentTheme /etc/nixos/configuration.nix 2>/dev/null | cut -d'"' -f2 || echo "tokyo-night")
+    CPU=$(lscpu | grep 'Model name' | cut -d':' -f2 | xargs)
+    MEMORY=$(free -h | awk '/^Mem:/ {print $2}')
+    DISK=$(df -h / | awk 'NR==2 {print $2}')
+
+    if [[ "''${OMNIXY_JSON:-}" == "1" ]]; then
+      echo "{"
+      echo "  \"system\": {"
+      echo "    \"version\": \"$VERSION\","
+      echo "    \"kernel\": \"$KERNEL\","
+      echo "    \"theme\": \"$THEME\","
+      echo "    \"user\": \"$USER\","
+      echo "    \"shell\": \"$SHELL\","
+      echo "    \"terminal\": \"$TERM\""
+      echo "  },"
+      echo "  \"hardware\": {"
+      echo "    \"cpu\": \"$CPU\","
+      echo "    \"memory\": \"$MEMORY\","
+      echo "    \"disk\": \"$DISK\""
+      echo "  }"
+      echo "}"
+      exit 0
+    fi
+
+    if [[ "''${OMNIXY_QUIET:-}" == "1" ]]; then
+      echo "version=$VERSION"
+      echo "kernel=$KERNEL"
+      echo "theme=$THEME"
+      echo "user=$USER"
+      echo "shell=$SHELL"
+      echo "terminal=$TERM"
+      echo "cpu=$CPU"
+      echo "memory=$MEMORY"
+      echo "disk=$DISK"
+      exit 0
+    fi
+
     echo "╭──────────────────────────────╮"
     echo "│       OMNIXY NIXOS           │"
     echo "╰──────────────────────────────╯"
     echo ""
     echo "System Information:"
     echo "==================="
-    echo "Version:     $(nixos-version)"
-    echo "Kernel:      $(uname -r)"
-    echo "Theme:       $(grep currentTheme /etc/nixos/configuration.nix 2>/dev/null | cut -d'"' -f2 || echo "default")"
+    echo "Version:     $VERSION"
+    echo "Kernel:      $KERNEL"
+    echo "Theme:       $THEME"
     echo "User:        $USER"
     echo "Shell:       $SHELL"
     echo "Terminal:    $TERM"
     echo ""
     echo "Hardware:"
     echo "========="
-    echo "CPU:         $(lscpu | grep 'Model name' | cut -d':' -f2 | xargs)"
-    echo "Memory:      $(free -h | awk '/^Mem:/ {print $2}')"
-    echo "Disk:        $(df -h / | awk 'NR==2 {print $2}')"
+    echo "CPU:         $CPU"
+    echo "Memory:      $MEMORY"
+    echo "Disk:        $DISK"
     echo ""
     echo "Quick Commands:"
     echo "=============="
-    echo "  omnixy-help     - Show help"
-    echo "  omnixy-update   - Update system"
-    echo "  omnixy-clean    - Clean system"
-    echo "  omnixy-theme    - Change theme"
+    echo "  omnixy help     - Show help"
+    echo "  omnixy update   - Update system"
+    echo "  omnixy clean    - Clean system"
+    echo "  omnixy theme    - List themes"
     EOF
     chmod +x $out/bin/omnixy-info
 
@@ -339,6 +454,27 @@ pkgs.stdenv.mkDerivation rec {
     cat > $out/bin/omnixy << 'EOF'
     #!/usr/bin/env bash
 
+    # Parse global flags
+    QUIET=false
+    JSON=false
+    while [[ $# -gt 0 ]]; do
+      case $1 in
+        --quiet|-q)
+          QUIET=true
+          export OMNIXY_QUIET=1
+          shift
+          ;;
+        --json)
+          JSON=true
+          export OMNIXY_JSON=1
+          shift
+          ;;
+        *)
+          break
+          ;;
+      esac
+    done
+
     CMD="''${1:-help}"
     shift || true
 
@@ -350,11 +486,25 @@ pkgs.stdenv.mkDerivation rec {
         omnixy-clean "$@"
         ;;
       theme)
-        if [ -n "$1" ]; then
-          omnixy-theme-set "$@"
-        else
-          omnixy-theme-list
-        fi
+        case "''${1:-}" in
+          set)
+            shift
+            omnixy-theme-set "$@"
+            ;;
+          list|ls)
+            omnixy-theme-list "$@"
+            ;;
+          get|current)
+            omnixy-theme-get "$@"
+            ;;
+          "")
+            omnixy-theme-list "$@"
+            ;;
+          *)
+            # Legacy: assume it's a theme name
+            omnixy-theme-set "$@"
+            ;;
+        esac
         ;;
       search)
         omnixy-search "$@"
@@ -369,8 +519,10 @@ pkgs.stdenv.mkDerivation rec {
         omnixy-help "$@"
         ;;
       *)
-        echo "Unknown command: $CMD"
-        echo "Run 'omnixy help' for available commands"
+        if [[ "$QUIET" == "false" ]]; then
+          echo "Unknown command: $CMD" >&2
+          echo "Run 'omnixy help' for available commands" >&2
+        fi
         exit 1
         ;;
     esac