Peculume.Grimoire.Plugin.Abstractions 0.2.1

Peculume.Grimoire.Plugin.Abstractions

The Grimoire Plugin Abstractions package provides a minimal, stable interface for building plugins that integrate with Grimoire-powered platforms.

It defines how a plugin should expose functionality to the host system (such as custom endpoints or service behaviors), as well as utility classes for result formatting and configuration access.

📦 Install via NuGet:

dotnet add package Peculume.Grimoire.Plugin.Abstractions

✨ Getting Started

To create a plugin for Grimoire, implement the IGrimoirePlugin interface:

using Peculume.Grimoire.Plugin.Abstractions;

public class MyPlugin : IGrimoirePlugin
{
    public void Register(IPluginContext context)
    {
        // GET /plugins/{instanceId}
        context.MapGet("", () =>
            GrimoireResult.Ok(new { message = "Hello, world!", instance = context.InstanceId }));

        // GET /plugins/{instanceId}/healthcheck
        context.MapGet("healthcheck", () =>
            GrimoireResult.Ok(new { ok = true, ts = DateTimeOffset.UtcNow }));

        // Async handler example
        context.MapGet("config", async () =>
        {
            await Task.Yield();
            var apiKey = context.GetConfig("EXAMPLE_KEY");
            if (string.IsNullOrWhiteSpace(apiKey))
                return GrimoireResult.BadRequest("Missing 'EXAMPLE_KEY' config.");

            return GrimoireResult.Ok(new { hasKey = true });
        });
    }
}

🗺️ Do not start your route with /. Pass "", "healthcheck", "api/things", etc. The host prefixes with BasePath automatically.

🧱 Interfaces

IGrimoirePlugin

Entry point for every plugin. The host creates an instance and calls Register with a per-installation context.

public interface IGrimoirePlugin
{
    void Register(IPluginContext context);
}

IPluginContext

A runtime context scoped to a single plugin installation (instance). It exposes the instance identity, base path, route mapping helpers, and configuration access.

public interface IPluginContext
{
    Guid InstanceId { get; }                  // Unique per installation
    string BasePath { get; }                  // e.g. "/plugins/{instanceId}"

    // Route mapping (auto-prefixed with BasePath)
    void MapGet(string route, Func<GrimoireResult> handler);
    void MapGet(string route, Func<Task<GrimoireResult>> handler);

    // Instance-scoped configuration
    string? GetConfig(string key);
}

GrimoireResult

A small response envelope that your handlers return. The host converts it into an HTTP response.

public class GrimoireResult
{
    public int StatusCode { get; set; } = 200;
    public string ContentType { get; set; } = "application/json";
    public object? Body { get; set; }

    public static GrimoireResult Ok(object body);
    public static GrimoireResult BadRequest(object body);
}

🔌 Routing model (per-instance mounting)

• The host loads each installed plugin and assigns a unique base path (e.g., /plugins/{instanceId}).
• Your plugin never hardcodes org names or absolute URLs.
• Multiple plugins—even with the same display name and namespaces—can coexist because routes are mounted under different instance IDs.

Example effective routes (host):

• GET /plugins/5f2f1f2a-.../ → your context.MapGet("")
• GET /plugins/5f2f1f2a-.../healthcheck → your context.MapGet("healthcheck")

📜 License

Licensed under the Apache 2.0 License. See LICENSE.txt for details.

🤝 Contributing

This is a low-level dependency shared across plugin implementations. If you'd like to propose changes to the plugin contract, please open an issue or contribute via pull request.

🧙‍♀️ About Grimoire

Grimoire is an internal developer platform (IDP) framework for building composable tooling via pluggable backend and UI extensions. This package defines the runtime contract plugins use to integrate with the Grimoire host.