Ninja Core

A powerful, cross-platform package manager and runtime for managing tools and plugins (called "shurikens").

Overview

Ninja Core is a Rust library that provides a comprehensive framework for installing, configuring, and managing executable packages with embedded scripting, templating, and process management capabilities.

Features

• Shuriken Management: Install, configure, and run packages ("shurikens") with ease
• State Management: Track and manage shuriken states (running, idle, error)
• Lua Scripting: Embedded Lua scripting engine for dynamic configuration and automation
• Backup & Restore: Backup and restore shuriken configurations and states
• Cross-Platform: Full support for Linux, macOS, and Windows
• Template Engine: Tera-powered templating for configuration files
• Elevated Permissions: Seamless admin/sudo execution across platforms
• Remote Downloads: Download shurikens from registries
• DSL Support: Domain-specific language for easy shuriken control

Architecture

The library is organized into modular components:

• manager: Central system for managing shurikens and processes
• shuriken: Package representation and execution
• scripting: Lua engine, DSL parser, and template engine
• common: Shared types, configuration, error handling, and registry
• backup: Backup and restore functionality
• utils: Helper functions for downloads and file operations

Key Concepts

Shurikens

A "shuriken" is a managed package that can be:

• Installed from local or remote sources
• Configured with platform-specific settings
• Started, stopped, and monitored
• Scripted with Lua hooks
• Backed up and restored

States

Each shuriken can be in one of three states:

• Running: Active and executing
• Idle: Installed but not running
• Error: Failed state with error message

File Format

The .shuriken file is a custom binary format with the following structure:

[Magic bytes (6 bytes)]
[Metadata length (4 byte u32)]
[Metadata (CBOR)]
[Archive length (4 byte u32)]
[Archive (Gzip TAR)]
[Archive hash (32 byte SHA-256)]

For debugging, use shuriken.hexpat in the assets directory with ImHex to inspect the binary structure.

Usage

As a Library

Add to your Cargo.toml:

[dependencies]
ninja-core = { path = "path/to/ninja-core" }

Basic Example

use ninja::manager::ShurikenManager;
use std::path::Path;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create a manager
    let manager = ShurikenManager::new().await?;
    
    // Install a shuriken
    manager.install(Path::new("path/to/shuriken.shuriken")).await?;
    
    // Start it
    manager.start("my-shuriken").await?;
    
    Ok(())
}

DSL Commands

The built-in DSL supports various commands:

select <name>            # Select a shuriken
start                    # Start selected shuriken
stop                     # Stop selected shuriken
configure                # Configure selected shuriken
configure { k = v }      # Apply config assignments
get <key>                # Get a config value
set <key> <value>        # Set a config value
toggle <key>             # Toggle a boolean config value
install <path>           # Install a shuriken from file
list                     # List all shurikens
list state               # List shurikens with states
execute <script>         # Execute a Ninja script file
http start <port>        # Start the HTTP server (via CLI)
exit                     # Deselect current shuriken
help                     # Show help message

Platform Support

Linux

• Uses pkexec for elevated permissions
• Full process management with signals

macOS

• Uses osascript for GUI elevation prompts
• Native process control

Windows

• UAC integration for elevated permissions
• Windows API process management

Dependencies

Key dependencies include:

• tokio: Async runtime
• mlua: Lua scripting engine
• tera: Template engine
• serde: Serialization framework
• anyhow: Error handling
• opendal: Unified data access layer
• reqwest: HTTP client
• tar/flate2: Archive handling

Configuration

Shurikens are configured using TOML files with support for:

• Platform-specific paths
• Environment variables
• Template variables
• Nested configurations
• Custom fields

Building

# Build the library
cargo build --release

# Run tests
cargo test

# Build documentation
cargo doc --open

License

See the license file in the workspace root.

Contributing

Contributions are welcome! Please follow the project's coding standards and include tests for new features.