Meows.Plugins.Abstractions 1.5.0

Meows.Plugins.Abstractions

The contract a Meows plugin implements. Reference this package and you can write a plugin in your own repository, with no copy of the Meows sources at all.

Meows is a Windows desktop companion built on Avalonia. It is a shell: it finds plugins, lets you switch them on, and gives each one a tab. Everything useful is a plugin.

Writing one

using Avalonia.Controls;
using Meows.Plugins.Abstractions;

public sealed class MyPlugin : IMeowsPlugin
{
    public string Id => "me.my-plugin";      // stable forever: it is the settings key
    public string DisplayName => "My Plugin";
    public string Description => "One sentence, shown on the Plugins tab.";
    public string? Icon => "🎲";
    public string? Category => "group.everyday";  // optional heading on the Plugins tab

    public Control CreateView(IMeowsHost host) =>
        new MyView { DataContext = new MyViewModel(host) };
}

Your project needs net10.0, and Avalonia referenced with ExcludeAssets="runtime", because the shell supplies Avalonia and the contract at runtime. Both must stay a single copy or the shell cannot host the control you hand back.

<PackageReference Include="Avalonia" Version="12.1.1" ExcludeAssets="runtime" />
<PackageReference Include="Meows.Plugins.Abstractions" Version="1.5.0" ExcludeAssets="runtime" PrivateAssets="all" />

There is a dotnet new template that writes all of this for you:

dotnet new install Meows.Plugins.Template
dotnet new meows-plugin -n MyPlugin

What the host gives you

IMeowsHost provides a private data directory, JSON settings, the shared log, the notification surface, background work the shell cancels when your plugin is switched off, and the language the window is in.

Joining in with rules

The Rules tab says when one plugin records something, then ask another to act. Offer what yours can be asked for in IMeowsPlugin.Actions, name the kinds of event it records in IMeowsPlugin.Records, and have the view model implement IActionTarget, which returns one sentence for the History tab. The shell keeps a rule from starting another rule, so a plugin never has to think about loops. See PLUGIN-GUIDE.md.

Reaching the server

IMeowsHost.Reach is the server set on Meows' Settings tab, a share or SFTP. Name a place under its root, hand over a folder, and read what came back: await host.Reach.CopyFolder(folder, "Data/modules/my-module/drop"). Which of the two it is, and the key for SFTP, stay with the shell.

Colours and language

The window is light or dark, and English or German, depending on what the person chose. Both reach your plugin by name at run time, so neither needs a reference to the shell:

<Border Background="{DynamicResource MeowsCard}" BorderBrush="{DynamicResource MeowsLine}">
    <TextBlock Text="{m:Tr myplugin.title}" />
</Border>

{m:Tr} reads a key out of a Strings.<code>.json you ship as an embedded resource; host.Text does the same from code. A key nobody has is shown as the key, and a key your language is missing reads in English. A plugin that uses neither still works: it stays in English and paints its own colours in every theme.

{m:Tr} follows a language change on its own. Anything your view model works out in code does not, so hold a LanguageWatch(OnEverythingChanged) for its lifetime and dispose it with everything else.

The template writes all of this out for you, and PLUGIN-GUIDE.md lists the colour tokens.

Installing your plugin

Build it, then put the output in its own folder under the plugins directory beside Meows.exe, named after the folder:

plugins/MyPlugin/MyPlugin.dll

Or keep it anywhere and point MEOWS_PLUGINS_DIR at the folder holding it, which adds to the search rather than replacing it. Meows.exe --list-plugins says what was found and why anything was refused.

Versioning

This package carries the contract version, which moves independently of the app. The shell refuses a plugin built against a newer contract, or a different major, and says so on the plugin's card rather than failing later. An older minor is fine, since additions stay backward compatible.

1.0.0 is the first stable contract: within 1.x a member is only added, never removed or changed. What came with it: IMeowsHost.Pick, the shell's file dialogs for a view model, and IMeowsPlugin.WhileOff, a way to be searched from Ctrl+K while switched off, through IMeowsDormantHost. Both have defaults. Plugins built against 0.x need a rebuild.

Full documentation: PLUGIN-GUIDE.md

MIT licensed.