omnixy/packages/README.md

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:

{ 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:

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:

# 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:

# Human-readable (default)
omnixy info

# Machine-readable
omnixy --json info | jq .system.version

# Scriptable
omnixy --quiet update && echo "Updated successfully"

Composability:

# 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:

# packages/my-tool.nix
{ pkgs, lib, ... }:
pkgs.stdenv.mkDerivation rec {
  pname = "my-tool";
  version = "1.0.0";

  # Package definition
}

2. Add to Flake:

# In flake.nix packages section
my-tool = pkgs.callPackage ./packages/my-tool.nix {};

3. Install in System:

# 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

# 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

# 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.