Plugin System - Hype - Zero-Dependency App Dev

🚀 Quick Start

Using an Existing Plugin

# Run a script with a plugin
./hype run myapp.lua --plugins fs@1.0.0

# Build an executable with embedded plugin
./hype build myapp.lua --plugins fs@1.0.0 -o myapp

-- In your Lua script
local fs = require("fs")
local content, err = fs.readFile("config.txt")
if content then
    print("Config:", content)
else
    print("Error:", err)
end

Creating a Simple Plugin

1. Create plugin directory

mkdir my-plugin && cd my-plugin

2. Create manifest (hype-plugin.yaml)

name: "my-plugin"
version: "1.0.0"
type: "lua"
main: "plugin.lua"
description: "My awesome plugin"

3. Create plugin code (plugin.lua)

local myplugin = {}

function myplugin.greet(name)
    return "Hello, " .. (name or "World") .. "!"
end

return myplugin

4. Use the plugin

./hype run test.lua --plugins ./my-plugin

📦 Using Plugins

Command Line Usage

# Single plugin by name
./hype run app.lua --plugins fs

# With specific version
./hype run app.lua --plugins fs@1.0.0

# Multiple plugins
./hype run app.lua --plugins fs@1.0.0,json,utils@2.0.0

# With custom aliases
./hype run app.lua --plugins filesystem=fs@1.0.0,parser=json@1.5.0

Plugin Specifications

fs

Simple name, auto-discovery

fs@1.0.0

Name with version

myfs=./path/to/plugin

Custom alias

myfs=./path/to/plugin@2.0.0

Alias with version

🔍 Plugin Discovery

Auto-Discovery Locations

When using simple names, Hype searches these locations:

./plugins/[name]/
./examples/plugins/[name]/
./[name]-plugin/
./examples/plugins/[name]-plugin/

Plugin Structure

my-plugin/
├── hype-plugin.yaml    # Required: Plugin manifest
├── plugin.lua          # Required: Main plugin code
├── README.md           # Optional: Documentation
├── LICENSE             # Optional: License file
└── examples/           # Optional: Usage examples
    └── demo.lua

⚙️ Plugin Manifest

Required Fields

name: "my-plugin"           # Plugin name (used in require())
version: "1.0.0"           # Semantic version
type: "lua"                # Plugin type (currently only "lua")
main: "plugin.lua"         # Entry point file

Optional Fields

description: "Description of what the plugin does"
author: "Your Name "
license: "MIT"
homepage: "https://github.com/user/my-plugin"
repository: "https://github.com/user/my-plugin.git"

🏗️ Plugin Development

Plugin Code Structure

-- plugin.lua
local myplugin = {}

-- Simple function
function myplugin.hello(name)
    return "Hello, " .. (name or "World") .. "!"
end

-- Function with error handling (Lua convention)
function myplugin.divide(a, b)
    if b == 0 then
        return nil, "Division by zero"
    end
    return a / b, nil
end

-- Plugin metadata (optional but recommended)
myplugin._VERSION = "1.0.0"
myplugin._DESCRIPTION = "My awesome plugin"

-- Must return the plugin table
return myplugin

Best Practices

Follow Lua conventions: Return value, error for functions that can fail
Include metadata: Add _VERSION and _DESCRIPTION fields
Validate inputs: Check parameter types and values
Document functions: Include clear function descriptions
Handle errors gracefully: Use proper error handling patterns

📚 Available Plugins

🗂️ Filesystem Plugin (fs@1.0.0)

Basic file and directory operations

fs.readFile(path) - Read file contents
fs.writeFile(path, content) - Write file contents
fs.exists(path) - Check file existence
fs.size(path) - Get file size
fs.listDir(path) - List directory contents
fs.mkdir(path) - Create directory

🗂️ Enhanced Filesystem Plugin (fs@2.0.0)

Advanced file operations with additional features

All v1.0.0 features plus:
fs.copyFile(src, dst) - Copy file
fs.moveFile(src, dst) - Move file
fs.deleteFile(path) - Delete file
fs.version() - Get plugin version

💡 Examples

File Operations Example

local fs = require("fs")

-- Read configuration
local config, err = fs.readFile("config.json")
if not config then
    print("Error:", err)
    return
end

-- Create backup
local success, err = fs.copyFile("data.txt", "backup.txt")
if success then
    print("Backup created successfully")
end

-- List files
local files, err = fs.listDir("./logs")
if files then
    for _, file in ipairs(files) do
        print("Found:", file)
    end
end

Multiple Plugins Example

-- Use multiple plugins
local fs = require("fs")
local utils = require("utils")

-- Enhanced file operations
local data = fs.readFile("data.json")
if data then
    local processed = utils.processData(data)
    fs.writeFile("processed.json", processed)
end

-- Version information
print("FS Plugin Version:", fs._VERSION)
print("Utils Plugin Version:", utils._VERSION)

🔧 Version Management

Plugin Versioning

# Use specific version
./hype run app.lua --plugins fs@1.0.0

# Use latest available
./hype run app.lua --plugins fs

# Multiple versions with aliases
./hype run app.lua --plugins fs1=fs@1.0.0,fs2=fs@2.0.0

Version Compatibility

-- Check plugin version in your code
local fs = require("fs")

if fs._VERSION then
    print("Using fs plugin version:", fs._VERSION)
    
    -- Version-specific features
    if fs._VERSION >= "2.0.0" and fs.copyFile then
        fs.copyFile("source.txt", "dest.txt")
    else
        print("copyFile not available in this version")
    end
end

🔍 Troubleshooting

Common Issues

Plugin not found

                            Error: failed to load plugin fs: failed to fetch plugin: unsupported plugin source: fs
                        

Check plugin exists in search paths
Try explicit path: --plugins ./path/to/plugin

Version mismatch

                            Error: version validation failed: plugin version mismatch: requested 2.0.0, found 1.0.0
                        

Check plugin manifest version
Use correct version or @latest

Debug Tips

Test plugin independently: lua plugin.lua
Use development mode: ./hype run --plugins fs test.lua
Check plugin locations: ls -la ./plugins/fs/
Validate manifest: Check YAML syntax