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

Run the CLI:
```
pkljar
```
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
Choose a module to evaluate (e.g., Config, Docker, Starship)
Specify output directory and format
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:

Package selection
Module selection
Output directory configuration
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

Create a new directory in packages/ following the naming convention:
```
mkdir packages/myorg.myservice
```

Create a PklProject file:

amends "../../basePklProject.pkl"

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

Define your configuration modules
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

Fork the repository
Create a feature branch
Make your changes
Run tests: pkl test packages/*/
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