Utilities for building Delve plugins. This repository ships two packages that work together:

• Go module github.com/PortableSheep/delve-sdk for authoring plugin backends
• npm package @delve/plugin-sdk for frontend command bridging

The sections below describe what each package provides today.

• The current Go SDK version is exposed as sdk.Version (e.g. v0.5.0). Plugins should include this value in their registration payloads so the host can reject incompatible builds early.
• sdk.CompatibleHostRange documents the Delve host versions the SDK is tested with. Future releases will expand this range; treat it as the source of truth when shipping plugins.
• JSON schema helpers sdk.PluginManifestSchema() and sdk.LayoutSchema() are available for validating plugin.json manifests and persisted docking layout state. These are the same schemas the Delve host enforces at runtime.

• go-utility: Full-featured Go plugin with frontend
• theme: CSS theme plugin
• integration: API integration plugin
• dashboard: Data visualization plugin

customTemplate := &sdk.PluginTemplate{
    Name:        "custom-api",
    Description: "Custom API integration template",
    Type:        "integration",
    Language:    "go",
    Files: []sdk.TemplateFile{
        {
            Path:     "main.go",
            Template: true,
            Content:  "// Custom template content with {{.Variables}}",
        },
    },
    Variables: map[string]interface{}{
        "APIVersion": "v1",
    },
}

enhancedSDK.Generator().RegisterTemplate(customTemplate)

config := sdk.SDKConfig{
    RegistryURL:   "https://registry.delve.sh",
    SecurityLevel: sdk.SecurityLevelMedium,
    CacheEnabled:  true,
    DevMode:       false,
    LogLevel:      sdk.LogLevelInfo,
    CustomTemplates: map[string]*sdk.PluginTemplate{
        "my-template": customTemplate,
    },
}

sdk := sdk.NewEnhancedSDK(config)

• EnhancedSDK - Main SDK interface
• EnhancedPlugin - Enhanced plugin interface with lifecycle methods
• SecurityManager - Handles security policies and sandboxing
• EnhancedRegistry - Advanced plugin registry with search and metadata
• SchemaValidator - Plugin configuration validation
• PluginGenerator - Template-based plugin generation
• DevTools - Development and build tools

• SecurityLevel - Security level enumeration
• SecurityPolicy - Security policy configuration
• Permission - Permission request structure
• Sandbox - Isolated execution environment

• EnhancedPluginInfo - Complete plugin metadata
• RegistrySearchFilter - Advanced search filtering
• PluginMetrics - Usage and performance metrics

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• Issues: GitHub Issues

Store a key-value pair in plugin storage.

Retrieve a value from plugin storage.

Delete a key from plugin storage.

List all keys in plugin storage.

Clear all plugin storage.

The heartbeat system provides robust connection monitoring:

1. Plugin sends heartbeat every interval seconds
2. Host responds with heartbeat acknowledgment
3. Plugin tracks last successful heartbeat response

1. If no heartbeat response received within timeout
2. Plugin logs timeout warning
3. Calls StateManager.SaveState() if configured
4. Plugin shuts down gracefully

• Prevents zombie processes when host crashes
• Saves plugin state before unexpected shutdown
• Reduces resource usage by cleaning up orphaned plugins
• Improves system stability

plugin, err := sdk.Start(pluginInfo)
if err != nil {
    log.Printf("Failed to connect: %v", err)
    // Handle connection failure
}

err := plugin.SetItem("key", "value")
if err != nil {
    log.Printf("Storage error: %v", err)
    // Handle storage failure
}

// Recommended for all production plugins
plugin.StartHeartbeat(30*time.Second, 60*time.Second)

type MyPlugin struct {
    importantData map[string]interface{}
    configPath    string
}

func (p *MyPlugin) SaveState() error {
    // Save critical state that should survive restarts
    return saveToFile(p.configPath, p.importantData)
}

import (
    "os"
    "os/signal"
    "syscall"
)

// Listen for OS signals
sigChan := make(chan os.Signal, 1)
signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)

go func() {
    <-sigChan
    log.Println("Shutting down gracefully...")
    plugin.Close()
    os.Exit(0)
}()

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

go func() {
    ticker := time.NewTicker(10 * time.Second)
    defer ticker.Stop()

    for {
        select {
        case <-ctx.Done():
            return
        case <-ticker.C:
            // Do background work
        }
    }
}()

plugin.Listen(func(messageType int, data []byte) {
    log.Printf("Received message type %d: %s", messageType, string(data))
    // Process message
})

Plugins can extend the Delve UI with sidebar items and footer widgets, and update them live at runtime.

Helpers on Plugin:

• SetUIContributions(c UIContributions) – replace all sidebar/footer entries
• UpsertSidebarItem(item SidebarItem) – insert or replace a sidebar item and emit an update
• UpsertFooterWidget(w FooterWidget) – insert or replace a footer widget and emit an update
• SetFooterBadgeCount(identifier string, count int) – update a footer widget badge by ElementTag or Title

Minimal usage:

// During registration
pluginInfo := &sdk.RegisterRequest{
    Name:             "my-plugin",
    Description:      "Demo",
    CustomElementTag: "my-plugin",
    UiComponentPath:  "frontend/component.js",
}
plugin, _ := sdk.Start(pluginInfo)

// Contribute a sidebar item and a footer icon
_ = plugin.SetUIContributions(sdk.UIContributions{
    Sidebar: []sdk.SidebarItem{
        { Title: "My Plugin", ElementTag: "my-plugin", ComponentPath: "frontend/component.js", OnClickCommand: &sdk.CommandRef{ID: "my-plugin.open"} },
    },
    Footer: []sdk.FooterWidget{
        { Title: "My Plugin", Icon: "mdi:rocket", OnClickCommand: &sdk.CommandRef{ID: "my-plugin.open"} },
    },
})

// Update badge later (e.g., unread count)
_ = plugin.SetFooterBadgeCount("My Plugin", 5)

// Default click handler returns an activation hint for the frontend
plugin.OnCommand("my-plugin.open", func(ctx context.Context, args []any) (any, error) {
    return map[string]any{"activateUI": map[string]any{"plugin": "my-plugin", "tag": "my-plugin"}}, nil
})

1. Startup: Plugin connects and registers with host
2. Running: Plugin processes messages and performs work
3. Heartbeat: Regular health checks with host
4. Shutdown: Graceful cleanup when connection lost or timeout
5. State Save: Critical data persisted before exit

To make your plugin available through the Delve Plugin Registry:

1. Create plugin.json with complete metadata including screenshots
2. Add screenshots to a screenshots/ directory in your repository
3. Submit to registry via pull request

Directory Structure:

my-plugin/
├── plugin.json           # Plugin metadata
├── main.go              # Plugin source code
├── frontend/
│   └── component.js     # Frontend component
├── screenshots/         # Plugin screenshots
    ├── overview.png
    ├── settings.png
    └── features.png

Your plugin's frontend component should match the CustomElementTag:

// If CustomElementTag is "my-plugin"
class MyPlugin extends HTMLElement {
    connectedCallback() {
        this.innerHTML = '<h1>My Plugin UI</h1>';
    }
}

customElements.define('my-plugin', MyPlugin);

• Check host-config.yml has plugin enabled
• Verify plugin executable exists and is executable
• Check plugin registration logs

• Ensure host is running on correct WebSocket port
• Check firewall settings
• Verify --ws-port flag is passed correctly

• Check host system resources
• Adjust timeout values for slower systems
• Monitor network connectivity

• Verify StateManager interface implementation
• Check file permissions for state files
• Review error logs during shutdown

See example.go for a complete plugin implementation with:

• Heartbeat monitoring
• State management
• Background work
• Graceful shutdown
• Signal handling

• Go 1.19 or later
• Delve host application
• WebSocket support