TildeMail.Scripting 0.2.0

TildeMail.Scripting

The Lua runtime and modules used to extend TildeMail. Use this library when composing a scripting-enabled host or adding a Lua module from a DLL plugin.

Responsibilities

• Script discovery, startup, reload and shutdown through IScriptEngine.
• Serialized, instruction-limited Lua execution and the embedded sandbox prelude.
• Standard modules: commands, events, gpg, keys, log, mail, rules and sys.
• Optional jobs and top_status modules, custom module/enum registration and generated definitions.lua metadata.

The library targets .NET 10 and directly references TildeMail.Core, TildeMail.Mail and Moongate.Scripting. Abstractions, the Lua runtime and the Core service dependencies are resolved transitively. The dependency direction is Scripting → Mail → Core → Abstractions; neither Core nor Mail depends on this library.

Example: a custom Lua module

using Moongate.Scripting.Attributes.Scripts;

namespace ExamplePlugin.Modules;

[ScriptModule("greetings", "A greeting module.")]
public sealed class GreetingModule
{
    [ScriptFunction(helpText: "Returns a greeting.")]
    public string Hello(string name)
    {
        return "Hello, " + name;
    }
}

Register the module in the host container or in a plugin's Register method, before the script engine starts:

using TildeMail.Scripting.Extensions;
using ExamplePlugin.Modules;

container.AddScriptModule<GreetingModule>();

A script can then call:

log.info(greetings.hello("TildeMail"))

Registration alone does not start a Lua engine. A host calls RegisterScripting(new ScriptEngineOptions { ScriptsDirectory = path }) and supplies the loaded TildeMailConfig, IMailBackendFactory, IGpgService and ISystemNotifier. It uses Core's RegisterHosting to run the registered lifecycle, or explicitly starts and stops IScriptEngine. Add RegisterJobs and RegisterJobScripting before startup when the job-backed modules are needed. Register services and modules before resolving or starting the engine.

Custom hosts that load Lua modules from DLL plugins pass typeof(IScriptEngine).Assembly to Core's PluginLoader as an additional shared assembly. This preserves the host's registry, module-attribute and Lua-value identities. The normal TildeMail application already does this. Use package versions matching the host; DLL plugins are trusted in-process code, not sandboxed Lua scripts.

See the scripting guide and plugin guide for the complete API and hosting rules.

Build and package

Run from the repository root with the .NET 10 SDK:

dotnet build src/TildeMail.Scripting -c Release
dotnet pack TildeMail.slnx -c Release -o artifacts/nuget

Packing the solution produces the four library packages together. The package contains the assembly with its embedded prelude, XML API documentation and this README. Core, Mail and Moongate.Scripting remain NuGet dependencies rather than copied DLLs; portable debug symbols are in the matching .snupkg. Version, authors and license metadata come from Directory.Build.props.

The NuGet development instructions explain local installation. Generating packages does not publish them to a registry.

License

GPL-3.0-or-later. See the license and third-party notices for dependency licenses.