Plugin Development

This guide covers everything you need to know about developing plugins for Puppet using WebAssembly (WASM).

Getting Started

Prerequisites

Understanding of any programming language supported by Extism PDK
Basic knowledge of WebAssembly concepts
Familiarity with JSON for manifest files

Template Repository

Start by cloning the plugin template:

git clone https://github.com/Mr-1311/plugin_template_rust

Currently, only the Rust template is available, and other templates will be added in the future. However, you can develop plugins using any language supported by the Extism PDK right now.

Check out template project readme for more information: plugin_template_rust

Required Functions

Every plugin must implement these three core functions:

// Initialize and return initial menu items
init(): List<{name: string, desc: string, icon: string}>

// Filter or update items based on user input
filter(query: string): List<{name: string, desc: string, icon: string}>

// Handle item selection
on_selected(selected: string): void

Note about icons:

For local images: Provide the full path to the image file
For Font Awesome icons: Use the Unicode value (e.g., “f0f3” for bell icon)
Supported image formats:
- PNG (.png)
- JPEG (.jpg, .jpeg)
- GIF (.gif)
- WebP (.webp)
- BMP (.bmp)
- WBMP (.wbmp)
- ICO (.ico, .icon)
- ICNS (.icns)
- XPM (.xpm)
- SVG (.svg)

Plugin Manifest

Create a manifest.json file with plugin metadata and permissions:

{
  "name": "plugin_name",
  "description": "Plugin description",
  "author": "author_name",
  "source": "repository_url",
  "platforms": ["windows", "linux", "macos"],
  "allowedPaths": ["$HOME/.config", "/opt"],
  "allowedHosts": ["domain.com", "*"],
  "wasi": false,
  "cli": false,
  "pluginArgs": [
    {
      "name": "argument_name",
      "description": "argument_description",
      "defaultValue": "default_value",
      "type": "argument_type"
    }
  ]
}

System Integration

Host Function

Plugins can execute system commands using:

cli_run(command: string, args: string[]): string

Data Access

Read/write access to /data directory
Use data_dir_path config key for full data folder path
For path access you can use environment variables in paths (e.g., $HOME/.config and access this path in plugin like /HOME/.config)
Enable wasi: true for filesystem aclc data foederss For pathaccess you can use e and access this path in plugin like /HOME/.config

Platform Detection

Use platform config key for OS detection
Values: “windows”, “macos”, “linux”

Publishing Plugins

Create a Release
- Include required files:
  - readme.md
  - plugin.wasm
  - manifest.json
- Add any additional files for the data directory

Register Your Plugin

Fork puppet-plugins repository

Edit plugins.json:

{
  "name": "plugin name",
  "author": "author name",
  "description": "plugin description",
  "platforms": ["macos", "windows", "linux"],
  "repo": "github repo url"
}

Submit pull request

Publishing Guidelines

Use semantic versioning for releases
Ensure unique plugin names
Avoid using terms like “puppet” or “official” in names
Include all necessary fils
Avoid using terms like “puppet” or “official” in names
Include all necessary files in release assetes in release assets
Properly document plugin usage and arguments

Best Practices

Security

Request minimum required permissions
Use specific paths in allowedPaths
Carefully consider allowedHosts entries

Performance

Optimize item generation in init function
Implement efficient filtering
Handle errors gracefully

User Experience

Provide clear item descriptions
Use appropriate icons (local images or Font Awesome)
Include helpful plugin documentation

Icons

When using local images, ensure they are in a supported format
For Font Awesome icons, use the correct Unicode values

Debugging Tips

Test plugin with different inputs
Verify file permissions
Check platform compatibility
Validate manifest format
Test data directory access
Verify icon paths and formats