ProGit Plugin SDK

LSL-1.0 licensed SDK for building ProGit plugins in Lua or WASM.

Why LSL-1.0 (Sovereign)?

This SDK is intentionally licensed under LSL-1.0 (file-level copyleft) to:

• Allow proprietary plugins - Your app code stays yours
• Protect the engine - Modifications to SDK files must be shared back
• Patent disarmament - "Cold War" clause for mutual protection
• Legal certainty - Governed by Dutch Law (Amsterdam)

The ProGit TUI core uses LCL-1.0 (strong copyleft). Your plugins do NOT inherit this because they link to the SDK, not the Core.

See PLUGIN_LICENSING.md for details.

---

Features

• 🦀 Rust-native - Type-safe plugin trait system
• 🌙 Lua support - Lightweight scripting for simple integrations
• 🕸️ WASM support - High-performance compiled plugins with sandboxing
• 🔌 Hook system - Issue lifecycle, sync, merge requests, custom commands
• 🛡️ Sandboxed - Plugins run in isolated environments
• 📦 Zero dependencies on ProGit core - Clean separation

---

Quick Start

Lua Plugin

use progit_plugin_sdk::prelude::*;

let script = r#"
    plugin = {
        name = "hello-world",
        version = "1.0.0",
        author = "Your Name",
        hooks = {
            on_issue_created = true,
        }
    }
    
    function on_issue_created(issue)
        print("New issue: " .. issue.title)
        return { success = true }
    end
"#;

let mut plugin = LuaPlugin::from_string(script, "hello")?;
plugin.on_issue_created(&issue)?;

WASM Plugin

use progit_plugin_sdk::prelude::*;

let plugin = WasmPlugin::load("plugins/my_plugin.wasm")?;
plugin.on_issue_created(&issue)?;

---

Plugin Structure

Lua Plugin Template

-- SPDX-License-Identifier: Apache-2.0

plugin = {
    name = "my-plugin",
    version = "1.0.0",
    author = "Your Name",
    description = "Plugin description",
    hooks = {
        on_issue_created = true,
        on_issue_updated = true,
    }
}

function init()
    -- Called once when plugin loads
    print("Plugin initialized!")
end

function on_issue_created(issue)
    -- Called when an issue is created
    print("New issue: " .. issue.title)
    return { success = true }
end

function on_issue_updated(issue)
    -- Called when an issue is updated
    return { success = true }
end

WASM Plugin Template

See examples/wasm_plugin_template/ for a complete Rust → WASM plugin example.

---

Available Hooks

Hook	Trigger	Data
on_issue_created	Issue created	Issue
on_issue_updated	Issue updated	Issue
on_issue_deleted	Issue deleted	{ id: string }
on_status_changed	Issue status changed	Issue
on_sync_push	Before sync push	Issue[]
on_sync_pull	After sync pull	Issue[]
on_merge_request_created	MR created	MergeRequest
on_command(name)	Custom command	Custom

---

Examples

• examples/lua_hello_world.rs - Basic Lua plugin
• examples/jira_sync.lua - Sync issues to Jira
• examples/wasm_hello_world.rs - Basic WASM plugin

Run examples:

cargo run --example lua_hello_world

---

Architecture

┌──────────────────────────────────────────────────────────────┐
│  ProGit TUI Core (Rust)                                      │
│  LCL-1.0 Licensed (Strong Copyleft)                          │
│  NO proprietary code linked                                  │
└───────────────────────────┬──────────────────────────────────┘
                            │
                   progit-plugin-sdk (LSL-1.0)
                            │
┌───────────────────────────┴──────────────────────────────────┐
│  Community Plugins (Lua/WASM)                                │
│  ANY License (LCL/LSL/LUL/LVL or Proprietary)                │
│  Loaded at RUNTIME via SDK                                   │
└──────────────────────────────────────────────────────────────┘

Key Points:

• SDK is LSL-1.0 - "Commercial Bridge" allows proprietary plugins
• ProGit core is LCL-1.0 - strong copyleft, source always visible
• No static linking - plugins loaded at runtime
• Clean API boundary - zero license contagion for your code

---

Plugin Context

Plugins receive a PluginContext on initialization:

pub struct PluginContext {
    pub repo_path: String,
    pub user: Option<String>,
    pub env: HashMap<String, String>,
    pub config: HashMap<String, serde_json::Value>,
}

Access in Lua:

function init()
    print("Repository: " .. context.repo_path)
    print("User: " .. (context.user or "unknown"))
end

---

Issue Schema

pub struct Issue {
    pub id: String,
    pub title: String,
    pub description: String,
    pub status: String,              // "backlog" | "in-progress" | "done"
    pub tags: Vec<String>,
    pub assignee: Option<String>,
    pub effort: Option<u8>,          // 1-5
    pub blocked: bool,
    pub created: String,             // ISO 8601
    pub updated: String,             // ISO 8601
    pub due: Option<String>,         // ISO 8601
    pub metadata: HashMap<String, serde_json::Value>,
}

---

Building Plugins

Lua Plugins

Just write .lua files! No build step required.

WASM Plugins

# Install WASM target
rustup target add wasm32-wasi

# Build your plugin
cd my-plugin
cargo build --target wasm32-wasi --release

# Plugin is at: target/wasm32-wasi/release/my_plugin.wasm

---

Contributing

Built with ❤️ in Rust.

git clone https://git.maiwald.work/SSSS/progit-plugin-sdk
cd progit-plugin-sdk
cargo test
cargo fmt

License: LSL-1.0 (Sovereign)

---

License

Copyright (c) 2025 Markus Maiwald

Licensed under the Libertaria Sovereign License, Version 1.0. See LICENSE for details.

Plugin authors: You may license your plugins under ANY terms. See PLUGIN_LICENSING.md.

---

Made with 🔥 by developers, for developers.