sonr/packages/pkl

pkljar

Interactive CLI for generating type-safe Sonr Network configurations using Apple's Pkl language

Overview

pkljar is a comprehensive configuration management system for the Sonr Network that provides an interactive CLI to generate, validate, and distribute type-safe configuration files. Built on Apple's Pkl configuration language, it ensures compile-time validation and type safety for all service configurations.

Features

• 🎯 Interactive CLI - User-friendly prompts for selecting and configuring Pkl packages
• 📦 Pre-built Packages - Ready-to-use configuration packages for Sonr services
• 🔒 Type Safety - Compile-time validation using Pkl's strong typing system
• 🌐 Remote Package Resolution - Automatic fetching from mod.pkl.sh repository
• 🎨 Multiple Output Formats - Support for YAML, JSON, TOML, XML, and more
• 🐳 Docker Support - Multi-platform Docker images for containerized deployments

Installation

Using npm

npm install -g @sonr.io/pkljar

Using npx (no installation required)

npx @sonr.io/pkljar

Using Docker

docker run onsonr/pkljar eval_beam

Quick Start

1. Run the CLI:

   pkljar
   

2. Select a package from the interactive menu:

   • sonr.beam - Matrix/Element communication bridge
   • sonr.core - Core Sonr Network configuration
   • sonr.hway - Highway node configuration
   • sonr.testnet - Testnet deployment configuration

3. Choose a module to evaluate (e.g., Config, Docker, Starship)

4. Specify output directory and format

5. Configuration files are generated in your specified directory

Available Packages

sonr.beam

Matrix bridge configuration for Sonr Network communication.

Modules:

• Config.pkl - Main configuration
• Element.pkl - Element client configuration
• Hookshot.pkl - GitHub/GitLab bridge configuration
• Synapse.pkl - Matrix server configuration

sonr.core

Core Sonr Network blockchain configuration.

Modules:

• Config.pkl - Core network configuration
• Keys.pkl - Key management configuration
• UCAN.pkl - UCAN authorization configuration
• Wallet.pkl - Wallet service configuration

sonr.hway

Highway node configuration for network routing.

Modules:

• Config.pkl - Highway node configuration

sonr.testnet

Testnet deployment configurations.

Modules:

• Docker.pkl - Docker Compose configuration
• Starship.pkl - Kubernetes deployment via Starship

CLI Usage

Interactive Mode (Default)

pkljar

Launches an interactive prompt that guides you through:

1. Package selection
2. Module selection
3. Output directory configuration
4. Format selection (YAML, JSON, TOML, etc.)

Output Formats

The CLI supports multiple output formats:

• auto - Use module's default format
• yaml - YAML format
• json - JSON format
• jsonnet - Jsonnet format
• pcf - Pkl Configuration Format
• plist - Property List format
• properties - Java Properties format
• textproto - Text Protocol Buffer format
• xml - XML format

Development

Project Structure

pkljar/
├── src/
│   └── index.js        # CLI entry point
├── packages/           # Pkl package definitions
│   ├── sonr.beam/     # Matrix bridge packages
│   ├── sonr.core/     # Core network packages
│   ├── sonr.hway/     # Highway node packages
│   └── sonr.testnet/  # Testnet packages
├── docker/            # Docker configurations
└── Makefile          # Build automation

Building from Source

# Clone the repository
git clone https://github.com/sonr-io/pkljar.git
cd pkljar

# Install dependencies
npm install

# Run locally
npm start

# Build packages
make release

# Build Docker image
make docker

Creating Custom Packages

1. Create a new directory in packages/ following the naming convention:

   mkdir packages/myorg.myservice
   

2. Create a PklProject file:

   amends "../../basePklProject.pkl"
   
   dependencies {
     ["base.web"] = import("../base.web/PklProject")
   }
   

3. Define your configuration modules

4. Build and publish:

   make release
   

Docker Usage

Pre-built Commands

# Generate Beam configuration
docker run onsonr/pkljar eval_beam

# Generate Synapse configuration
docker run onsonr/pkljar eval_beam_synapse

# Generate Hookshot configuration
docker run onsonr/pkljar eval_beam_hookshot

Custom Evaluation

docker run -v $(pwd)/output:/output onsonr/pkljar \
  pkl eval -m /output https://mod.pkl.sh/sonr.core/Config.pkl

API Reference

Package Resolution

All packages are resolved from the mod.pkl.sh repository:

https://mod.pkl.sh/{package}/{module}

Example:

https://mod.pkl.sh/sonr.core/Config.pkl

Module Structure

Each Pkl module follows this structure:

@ModuleInfo { minPklVersion = "0.27.0" }
module package.name.ModuleName

// Type definitions
class ConfigClass {
  property: Type
}

// Configuration instance
config: ConfigClass = new ConfigClass {
  property = value
}

// Output configuration
output {
  renderer = new YamlRenderer {}
}

Advanced Configuration

Environment-Specific Overrides

Use Pkl's conditional logic for environment-specific configurations:

config = new ServiceConfig {
  host = if (env == "production") 
    "prod.example.com" 
  else 
    "localhost"
}

Multi-File Output

Generate multiple configuration files from a single module:

output {
  files {
    ["config/app.toml"] = appConfig.output
    ["config/client.toml"] = clientConfig.output
    ["docker-compose.yml"] = dockerConfig.output
  }
}

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: pkl test packages/*/
5. Submit a pull request

Support

• Issues: GitHub Issues
• Documentation: Pkl Language Documentation
• Community: Sonr Discord

License

ISC License - see LICENSE file for details.

Acknowledgments

• Built with Pkl by Apple
• CLI powered by @clack/prompts
• Pkl runtime by @pkl-community/pkl