flexdeck 0.1.1__py3-none-any.whl

flexdeck-0.1.1.dist-info/METADATA

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: flexdeck
+Version: 0.1.1
+Summary: Write FlexDeck plugins in Python: declare actions, values, events and feeds; test, pack and verify them against FlexDeck itself.
+License: MIT
+Keywords: flexdeck,plugin,sdk,deck,tablet
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <a href="https://flex-deck.com"><img alt="flexdeck" src="https://raw.githubusercontent.com/santoshpanna/FlexDeck/main/.github/assets/logo.svg" width="72"></a>
+</p>
+
+<h1 align="center">flexdeck (Python)</h1>
+
+<p align="center">
+  Write <a href="https://flex-deck.com">FlexDeck</a> plugins in Python.<br>
+  Standard library only. A packed plugin carries the SDK with it, so it runs on any Python 3.10+ with nothing else installed.
+</p>
+
+<p align="center">
+  <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-ecebe6?style=flat-square&labelColor=111113&logo=python&logoColor=white">
+  <img alt="No dependencies" src="https://img.shields.io/badge/dependencies-none-ecebe6?style=flat-square&labelColor=111113">
+  <a href="https://github.com/santoshpanna/FlexDeck/blob/main/docs/plugins.md"><img alt="Plugin guide" src="https://img.shields.io/badge/docs-plugin%20guide-ecebe6?style=flat-square&labelColor=111113"></a>
+</p>
+
+<br>
+
+## Start in a minute
+
+```sh
+pip install flexdeck
+flexdeck-plugin new lights "Desk lights"
+cd lights
+python -m unittest                 # its tests, without FlexDeck
+flexdeck-plugin verify             # ask FlexDeck itself whether it will work
+flexdeck-plugin pack               # lights-0.1.0.fdpkg, ready to install
+```
+
+## A whole plugin
+
+```python
+from flexdeck_plugin import Plugin, arg
+
+plugin = Plugin(id="lights", name="Desk lights", version="0.1.0", permissions=["network"])
+plugin.variable("lights.on", "bool", "Whether the lights are on")
+
+@plugin.action("toggle", "Turn the lights on or off", {"room": arg("text", "desk", "Which room")})
+def toggle(args, ctx):
+    ctx.vars.set({"lights.on": not ctx.vars.get("lights.on")})
+
+if __name__ == "__main__":
+    plugin.serve()
+```
+
+## Verify before you publish
+
+`verify` packs the plugin and runs it through the FlexDeck on this computer (`flexdeck verify-plugin`), exactly as an install would. It checks:
+
+- [x] its catalogue and gallery keys
+- [x] every action's example arguments
+- [x] its values, feeds and settings
+- [x] that it keeps to its own namespace and its declared events
+- [x] that it writes nothing but the protocol to stdout
+- [x] that it stops cleanly
+
+> [!WARNING]
+> `--run-actions` also runs every action with its examples, and those actions do real things.
+
+If FlexDeck is installed somewhere unusual, set `FLEXDECK_BIN` to its path.
+
+## See also
+
+- [Plugin guide](https://github.com/santoshpanna/FlexDeck/blob/main/docs/plugins.md): the full reference
+- [Official plugins](https://github.com/Questory-Labs/FlexDeck-Plugins)
+- [`@flexdeck/plugin-sdk`](https://www.npmjs.com/package/@flexdeck/plugin-sdk) for TypeScript · [`flexdeck-plugin-sdk`](https://crates.io/crates/flexdeck-plugin-sdk) for Rust
+
+<br>
+
+<p align="center"><sub>MIT licensed, so your plugins can use any license.</sub></p>

flexdeck-0.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+flexdeck-0.1.1.dist-info/licenses/LICENSE,sha256=mfGNNUvFyHn1fAQgOINcVwbaxWamdjjK2pNutD1o1K0,1070
+flexdeck_plugin/__init__.py,sha256=IcbLk4f5N5dKvnRfLxY-R3yWbdl73WlToHRt-qL7SqM,26727
+flexdeck_plugin/__main__.py,sha256=PRxnxz2ArBk5tFuGDZOD9Ohgata5F63-x80L5EIy5OU,2789
+flexdeck_plugin/conformance.py,sha256=8JnKMvPILmK403nSDGNfJhfrVlJ4BQ3ETnqQ6ZWSYqw,3214
+flexdeck_plugin/pack.py,sha256=djmrRAK2l-8uB2thgZ_kOqvHg8zPfOwn1W5OTxPbgFI,4416
+flexdeck_plugin/template.py,sha256=quE2F6q8kjzpfXypEPuD6GIB74UdDMQu-jSv9IOtJmw,4957
+flexdeck_plugin/testing.py,sha256=fE6OufoZRGR2zZHjrXO_-k0UuCQwyphSQetdeN8t1fQ,4164
+flexdeck-0.1.1.dist-info/METADATA,sha256=Y3FqGHruYAn6E2oa5O6d4muyGOKluyC3mZxAkFOf7dw,3188
+flexdeck-0.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+flexdeck-0.1.1.dist-info/entry_points.txt,sha256=5U2jfe3pGZU7BeIVD3BkklG31XKZOCMoGVcqxaS4_Cc,66
+flexdeck-0.1.1.dist-info/top_level.txt,sha256=oG_BLYGZA0Qn7BKcwc97jcNzlwC4RkVx1P93IV5fgLw,16
+flexdeck-0.1.1.dist-info/RECORD,,

flexdeck-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flexdeck-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+flexdeck-plugin = flexdeck_plugin.__main__:main

flexdeck-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Santosh Panna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flexdeck-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+flexdeck_plugin

flexdeck_plugin/__init__.py

@@ -0,0 +1,599 @@
+"""Write FlexDeck plugins in Python.
+
+A plugin is one :class:`Plugin` with actions, values, events and feeds
+declared on it; the SDK speaks the protocol (JSON-RPC over stdin/stdout, the
+same contract as the TypeScript SDK and ``crates/flexdeck-plugin-abi``)::
+
+    from flexdeck_plugin import Plugin, arg
+
+    plugin = Plugin(id="lights", name="Desk lights", version="0.1.0", permissions=["network"])
+    plugin.variable("lights.on", "bool", "Whether the desk lights are on")
+
+    @plugin.action("toggle", "Turn the desk lights on or off")
+    def toggle(args, ctx):
+        ctx.vars.set({"lights.on": not ctx.vars.get("lights.on")})
+
+    if __name__ == "__main__":
+        plugin.serve()
+
+Standard library only, so a packed plugin carries the SDK with it and runs
+on any Python 3.10+ with nothing installed.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import io
+import json
+import math
+import os
+import re
+import sys
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Iterable, List, Mapping, Optional, Union
+
+__all__ = [
+    "ABI_VERSION",
+    "Argument",
+    "Context",
+    "Plugin",
+    "PluginError",
+    "arg",
+    "is_valid_id",
+]
+
+#: The contract version this SDK speaks. A Python plugin needs ABI 4.
+ABI_VERSION = 4
+SUPPORTED_ABIS = (4,)
+KINDS = ("text", "number", "bool", "choice")
+PERMISSIONS = ("network", "notifications", "processes", "filesystem")
+MAX_SERIES_POINTS = 600
+MAX_IMAGE_BYTES = 256 * 1024
+IMAGE_MIMES = ("image/png", "image/jpeg", "image/webp")
+
+Value = Union[str, float, int, bool]
+
+_ID = re.compile(r"^[a-z][a-z0-9_-]{0,63}$")
+
+
+def is_valid_id(value: str) -> bool:
+    """Ids become variable namespaces, folder names and URL segments."""
+    return bool(_ID.match(value))
+
+
+class PluginError(Exception):
+    """A plugin defined in a way FlexDeck would refuse, said when it is defined."""
+
+
+def _require(condition: Any, message: str) -> None:
+    if not condition:
+        raise PluginError(f"flexdeck plugin: {message}")
+
+
+@dataclass
+class Argument:
+    """One argument of an action or feed. ``example`` must work: the editor
+    fills it in, and verification runs every action with it."""
+
+    kind: str
+    example: str
+    description: str = ""
+    choices: List[str] = field(default_factory=list)
+    optional: bool = False
+    #: Suggestions for the editor, asked for while someone fills the argument in:
+    #: ``suggest(args, ctx) -> [value | (value, label)]``.
+    suggest: Optional[Callable[[Dict[str, str], "Context"], Iterable[Any]]] = None
+
+    def dto(self, name: str) -> Dict[str, Any]:
+        return {
+            "name": name,
+            "description": self.description,
+            "example": self.example,
+            "kind": self.kind,
+            "choices": list(self.choices),
+            "optional": self.optional,
+        }
+
+
+def arg(kind: str, example: str, description: str = "", *, choices: Iterable[str] = (), optional: bool = False, suggest=None) -> Argument:
+    """An argument: ``arg("text", "desk", "Which room")``."""
+    return Argument(kind=kind, example=str(example), description=description, choices=list(choices), optional=optional, suggest=suggest)
+
+
+@dataclass
+class _Action:
+    description: str
+    run: Callable[[Dict[str, str], "Context"], Any]
+    arguments: Dict[str, Argument]
+    check: Optional[Callable[[Dict[str, str], "Context"], Optional[str]]] = None
+
+
+@dataclass
+class _Feed:
+    description: str
+    fields: Dict[str, Dict[str, str]]
+    arguments: Dict[str, Argument]
+    watch: Callable[[str, Dict[str, str], "Context"], Any]
+    unwatch: Optional[Callable[[str, "Context"], Any]] = None
+
+
+def _wrap(kind: str, value: Value) -> Dict[str, Any]:
+    if kind == "bool":
+        return {"kind": kind, "value": bool(value)}
+    if kind == "number":
+        return {"kind": kind, "value": float(value)}
+    return {"kind": kind, "value": str(value)}
+
+
+class _Vars:
+    def __init__(self, plugin: "Plugin") -> None:
+        self._plugin = plugin
+
+    def set(self, values: Mapping[str, Value]) -> None:
+        """Publish values for variables this plugin owns."""
+        wire = self._plugin._publish(values)
+        if wire:
+            self._plugin._notify("vars/set", {"values": wire})
+
+    def declare(self, variables: Mapping[str, Mapping[str, Any]], replace: bool = False) -> None:
+        """Declare variables at run time, one per scene, say:
+        ``{"obs.scene.live": {"kind": "bool", "description": "…"}}``."""
+        self._plugin._declare(variables, replace)
+
+    def get(self, name: str) -> Optional[Value]:
+        """The last value this plugin published."""
+        return self._plugin._published.get(name)
+
+
+class _Log:
+    def __init__(self, plugin: "Plugin") -> None:
+        self._plugin = plugin
+
+    def info(self, message: str) -> None:
+        self._plugin._notify("log", {"level": "info", "message": str(message)})
+
+    def warn(self, message: str) -> None:
+        self._plugin._notify("log", {"level": "warn", "message": str(message)})
+
+    def error(self, message: str) -> None:
+        self._plugin._notify("log", {"level": "error", "message": str(message)})
+
+
+class _Feed_:
+    def __init__(self, plugin: "Plugin", instance: str) -> None:
+        self._plugin = plugin
+        self._instance = instance
+
+    def set(self, values: Mapping[str, Value]) -> None:
+        """Publish one key's values: ``{"temp": 21}`` becomes ``<id>.@<instance>.temp``."""
+        plugin = self._plugin
+        feed = plugin._watching.get(self._instance)
+        _require(feed is not None, f"nothing is watching a feed as '{self._instance}'")
+        fields = plugin._feeds[feed].fields
+        fresh: Dict[str, Dict[str, str]] = {}
+        full: Dict[str, Value] = {}
+        for name, value in values.items():
+            spec = fields.get(name)
+            if spec is None:
+                plugin.ctx.log.error(f"'{name}' is not a field of the {feed} feed")
+                continue
+            full_name = f"{plugin.id}.@{self._instance}.{name}"
+            if full_name not in plugin._declared:
+                fresh[full_name] = spec
+            full[full_name] = value
+        if fresh:
+            plugin._declare(fresh, False)
+        plugin.ctx.vars.set(full)
+
+
+class Context:
+    """What an action, a sample and a feed get: settings, values, events, logs."""
+
+    def __init__(self, plugin: "Plugin") -> None:
+        self._plugin = plugin
+        self.id = plugin.id
+        self.vars = _Vars(plugin)
+        self.log = _Log(plugin)
+
+    @property
+    def settings(self) -> Dict[str, str]:
+        """This plugin's settings, defaults filled in. Never another plugin's."""
+        return dict(self._plugin._settings)
+
+    @property
+    def data_dir(self) -> Optional[str]:
+        """A folder of this plugin's own, kept across updates."""
+        return self._plugin._data_dir
+
+    def emit(self, event: str, payload: Optional[Mapping[str, str]] = None) -> None:
+        """Announce an event this plugin declares."""
+        if event not in self._plugin._events:
+            self.log.error(f"'{event}' is not a declared event")
+            return
+        self._plugin._notify("event/emit", {"event": event, "payload": {k: str(v) for k, v in (payload or {}).items()}})
+
+    def notify(self, title: str, body: str = "") -> None:
+        """Show a notification. Needs the ``notifications`` permission."""
+        self._plugin._notify("notify", {"title": title, "body": body})
+
+    def store_settings(self, values: Mapping[str, str]) -> None:
+        """Keep values for settings this plugin declares (a refreshed token)."""
+        for key in values:
+            _require(key in self._plugin._settings_spec, f"setting '{key}' is not declared, so it cannot be stored")
+        self._plugin._settings.update(values)
+        self._plugin._notify("settings/store", {"values": dict(values)})
+
+    def open_url(self, url: str) -> None:
+        """Open an http(s) address in the person's browser. Needs ``network``."""
+        _require(re.match(r"^https?://\S+$", url, re.I), f"'{url}' is not an http(s) address")
+        self._plugin._notify("host/open_url", {"url": url})
+
+    def put_image(self, data: bytes, mime: str) -> str:
+        """Hand over a picture (≤256 KiB); returns ``img:<sha256>`` for a value to hold."""
+        _require(mime in IMAGE_MIMES, f"'{mime}' is not an image type the agent shows")
+        _require(len(data) <= MAX_IMAGE_BYTES, f"the image is {len(data)} bytes; the limit is {MAX_IMAGE_BYTES}")
+        sha = hashlib.sha256(data).hexdigest()
+        self._plugin._notify("images/put", {"sha256": sha, "mime": mime, "data": base64.b64encode(data).decode("ascii")})
+        return f"img:{sha}"
+
+    def set_series(self, name: str, points: Iterable[float]) -> None:
+        """A value's recent history, oldest first, for a graph. At most 600 points."""
+        _require(name.startswith(f"{self.id}."), f"'{name}' must start with '{self.id}.'")
+        finite = [float(p) for p in points if isinstance(p, (int, float)) and math.isfinite(p)][-MAX_SERIES_POINTS:]
+        self._plugin._notify("series/set", {"name": name, "points": finite})
+
+    def feed(self, instance: str) -> _Feed_:
+        """Publish values for one key's run of a feed."""
+        return _Feed_(self._plugin, instance)
+
+
+class Plugin:
+    """A FlexDeck plugin. Declare on it, then :meth:`serve`."""
+
+    def __init__(
+        self,
+        id: str,
+        name: str,
+        version: str,
+        description: str = "",
+        author: str = "",
+        permissions: Iterable[str] = (),
+    ) -> None:
+        _require(is_valid_id(id), f"'{id}' is not a usable id (lowercase letters, digits, - and _)")
+        _require(re.match(r"^\d[0-9A-Za-z.+-]*$", version) and ".." not in version, f"'{version}' is not a version")
+        for permission in permissions:
+            _require(permission in PERMISSIONS, f"'{permission}' is not a permission: {', '.join(PERMISSIONS)}")
+        self.id = id
+        self.name = name
+        self.version = version
+        self.description = description
+        self.author = author
+        self.permissions = list(permissions)
+        self._actions: Dict[str, _Action] = {}
+        self._settings_spec: Dict[str, Dict[str, Any]] = {}
+        self._events: Dict[str, Dict[str, Any]] = {}
+        self._feeds: Dict[str, _Feed] = {}
+        self._presets: List[Dict[str, Any]] = []
+        self._declared: Dict[str, Dict[str, Any]] = {}
+        self._published: Dict[str, Value] = {}
+        self._watching: Dict[str, str] = {}
+        self._settings: Dict[str, str] = {}
+        self._data_dir: Optional[str] = None
+        self._sample: Optional[Callable[[List[str], Context], Optional[Mapping[str, Value]]]] = None
+        self._start: Optional[Callable[[Context], Any]] = None
+        self._stop: Optional[Callable[[Context], Any]] = None
+        self._settings_changed: Optional[Callable[[Context], Any]] = None
+        self._lock = threading.RLock()
+        self._out_lock = threading.Lock()
+        #: What the plugin sent the host unprompted. For tests.
+        self.sent: List[Dict[str, Any]] = []
+        self._write: Callable[[Dict[str, Any]], None] = self.sent.append
+        self.ctx = Context(self)
+
+    # ---- Declaring ---------------------------------------------------------------
+
+    def variable(self, name: str, kind: str, description: str = "", *, unit: Optional[str] = None, choices: Iterable[str] = (), read_only: bool = True) -> None:
+        """A live value a key can show and an automation react to, under ``<id>.``."""
+        prefix = f"{self.id}."
+        _require(name.startswith(prefix) and len(name) > len(prefix), f"variable '{name}' must start with '{prefix}'")
+        _require(kind in KINDS, f"variable '{name}': '{kind}' is not a kind: {', '.join(KINDS)}")
+        self._declared[name] = {"kind": kind, "description": description, "unit": unit, "choices": list(choices), "readOnly": read_only}
+
+    def setting(self, key: str, kind: str = "text", description: str = "", *, default: Optional[str] = None, choices: Iterable[str] = (), secret: bool = False) -> None:
+        """Configuration filled in once. A ``secret`` is never shown again."""
+        _require(kind in KINDS, f"setting '{key}': '{kind}' is not a kind")
+        self._settings_spec[key] = {"kind": kind, "description": description, "default": default, "choices": list(choices), "secret": secret}
+
+    def event(self, name: str, description: str = "", fields: Iterable[str] = ()) -> None:
+        """Something that happens, which an automation can be started by."""
+        self._events[name] = {"description": description, "fields": list(fields)}
+
+    def action(self, name: str, description: str, arguments: Optional[Mapping[str, Argument]] = None, *, check=None):
+        """Decorate a function ``run(args, ctx)`` as an action. It may return
+        ``{"state": "<look>"}`` for the key to show."""
+        arguments = dict(arguments or {})
+        for arg_name, argument in arguments.items():
+            _require(argument.kind in KINDS, f"{name}.{arg_name}: '{argument.kind}' is not a kind")
+            if argument.kind == "choice":
+                _require(argument.example in argument.choices, f"{name}.{arg_name}: the example must be one of its choices")
+
+        def register(run):
+            self._actions[name] = _Action(description=description, run=run, arguments=arguments, check=check)
+            return run
+
+        return register
+
+    def feed(self, name: str, description: str = "", *, fields: Mapping[str, Union[str, Mapping[str, str]]], arguments: Optional[Mapping[str, Argument]] = None, unwatch=None):
+        """Decorate ``watch(instance, args, ctx)``: values for one key, with its
+        own arguments (a city), published with ``ctx.feed(instance).set``."""
+        specs = {f: ({"kind": s, "description": ""} if isinstance(s, str) else {"kind": s["kind"], "description": s.get("description", "")}) for f, s in fields.items()}
+
+        def register(watch):
+            self._feeds[name] = _Feed(description=description, fields=specs, arguments=dict(arguments or {}), watch=watch, unwatch=unwatch)
+            return watch
+
+        return register
+
+    def preset(self, id: str, name: str, widget: Mapping[str, Any], *, category: str = "", description: str = "", w: int = 1, h: int = 1) -> None:
+        """A ready-made key for the gallery: a widget without id or place."""
+        self._presets.append({"id": id, "name": name, "category": category, "description": description, "w": w, "h": h, "widget": dict(widget)})
+
+    def sample(self, function):
+        """Decorate ``sample(wanted, ctx) -> {name: value}``: asked only for what a key shows."""
+        self._sample = function
+        return function
+
+    def on_start(self, function):
+        self._start = function
+        return function
+
+    def on_stop(self, function):
+        self._stop = function
+        return function
+
+    def on_settings_changed(self, function):
+        self._settings_changed = function
+        return function
+
+    # ---- What the host is told -------------------------------------------------
+
+    def manifest(self) -> Dict[str, Any]:
+        """What ``initialize`` answers with."""
+        manifest: Dict[str, Any] = {
+            "abi": ABI_VERSION,
+            "id": self.id,
+            "name": self.name,
+            "version": self.version,
+            "description": self.description,
+            "author": self.author,
+            "actions": [
+                {"action": n, "description": a.description, "arguments": [arg.dto(k) for k, arg in a.arguments.items()]}
+                for n, a in self._actions.items()
+            ],
+            "settings": [
+                {"key": k, "description": s["description"], "kind": s["kind"], "choices": s["choices"], "defaultValue": s["default"], "secret": s["secret"]}
+                for k, s in self._settings_spec.items()
+            ],
+            "events": [{"name": n, "description": e["description"], "fields": e["fields"]} for n, e in self._events.items()],
+            "permissions": list(self.permissions),
+        }
+        uses = ["series"]
+        if self._presets:
+            uses.append("presets")
+            manifest["presets"] = list(self._presets)
+        if self._feeds:
+            uses.append("feeds")
+            manifest["feeds"] = [
+                {
+                    "name": n,
+                    "description": f.description,
+                    "arguments": [arg.dto(k) for k, arg in f.arguments.items()],
+                    "fields": [{"name": k, "kind": s["kind"], "description": s["description"]} for k, s in f.fields.items()],
+                }
+                for n, f in self._feeds.items()
+            ]
+        manifest["uses"] = uses
+        return manifest
+
+    def variables(self) -> List[Dict[str, Any]]:
+        with self._lock:
+            return [{"name": n, "description": s.get("description", ""), "kind": s["kind"], "unit": s.get("unit"), "choices": s.get("choices", []), "readOnly": s.get("readOnly", True)} for n, s in self._declared.items()]
+
+    def _notify(self, method: str, params: Dict[str, Any]) -> None:
+        self._write({"jsonrpc": "2.0", "method": method, "params": params})
+
+    def _publish(self, values: Mapping[str, Value]) -> Dict[str, Any]:
+        wire: Dict[str, Any] = {}
+        with self._lock:
+            for name, value in values.items():
+                spec = self._declared.get(name)
+                if spec is None:
+                    self.ctx.log.error(f"'{name}' was never declared, so it was not published")
+                    continue
+                if self._published.get(name, object()) == value and type(self._published.get(name)) is type(value):
+                    continue
+                self._published[name] = value
+                wire[name] = _wrap(spec["kind"], value)
+        return wire
+
+    def _declare(self, variables: Mapping[str, Mapping[str, Any]], replace: bool) -> None:
+        prefix = f"{self.id}."
+        for name, spec in variables.items():
+            _require(name.startswith(prefix), f"variable '{name}' must start with '{prefix}'")
+            _require(spec.get("kind") in KINDS, f"variable '{name}': '{spec.get('kind')}' is not a kind")
+        with self._lock:
+            if replace:
+                for name in list(self._declared):
+                    if name not in variables:
+                        self._declared.pop(name, None)
+                        self._published.pop(name, None)
+            for name, spec in variables.items():
+                self._declared[name] = {"kind": spec["kind"], "description": spec.get("description", ""), "unit": spec.get("unit"), "choices": list(spec.get("choices", [])), "readOnly": spec.get("readOnly", True)}
+        self._notify("vars/declare", {"variables": self.variables(), "replace": replace})
+
+    def configure(self, settings: Mapping[str, str], data_dir: Optional[str] = None) -> None:
+        """Settings as ``initialize`` gives them, defaults filled in. For tests."""
+        defaults = {k: s["default"] for k, s in self._settings_spec.items() if s["default"] is not None}
+        self._settings = {**defaults, **dict(settings)}
+        self._data_dir = data_dir
+
+    # ---- Answering the host ----------------------------------------------------
+
+    def handle(self, method: str, params: Optional[Mapping[str, Any]] = None) -> Any:
+        """Answer one request as the host sends it. Raises for an error answer."""
+        body = dict(params or {})
+        ctx = self.ctx
+        if method == "initialize":
+            asked = body.get("abi")
+            if asked not in SUPPORTED_ABIS:
+                raise PluginError(f"this plugin speaks ABI {' or '.join(map(str, SUPPORTED_ABIS))}, the agent speaks {asked}")
+            self.configure(body.get("settings") or {}, body.get("dataDir"))
+            return {"manifest": self.manifest(), "variables": self.variables()}
+        if method == "variables":
+            return self.variables()
+        if method == "check":
+            action = self._actions.get(body.get("action", ""))
+            if action is None:
+                return {"ok": False, "error": f"no action called '{body.get('action')}'"}
+            problem = action.check(dict(body.get("args") or {}), ctx) if action.check else None
+            return {"ok": False, "error": str(problem)} if problem else {"ok": True}
+        if method == "invoke":
+            action = self._actions.get(body.get("action", ""))
+            if action is None:
+                return {"ok": False, "error": f"no action called '{body.get('action')}'"}
+            try:
+                result = action.run(dict(body.get("args") or {}), ctx)
+            except Exception as error:  # an action's failure is an answer, not a crash
+                return {"ok": False, "error": str(error) or type(error).__name__}
+            answer: Dict[str, Any] = {"ok": True}
+            if isinstance(result, Mapping) and isinstance(result.get("state"), str):
+                answer["state"] = result["state"]
+            return answer
+        if method == "sample":
+            with self._lock:
+                wanted = [n for n in body.get("wanted") or [] if n in self._declared]
+            if not wanted:
+                return {"values": {}}
+            returned = self._sample(wanted, ctx) if self._sample else None
+            self._publish(returned or {})
+            values = {}
+            with self._lock:
+                for name in wanted:
+                    if name in self._published:
+                        values[name] = _wrap(self._declared[name]["kind"], self._published[name])
+            return {"values": values}
+        if method == "choices":
+            action = self._actions.get(body.get("action", ""))
+            answer = {"arguments": {}}
+            if action is None:
+                return {**answer, "error": f"no action called '{body.get('action')}'"}
+            args = dict(body.get("args") or {})
+            for name, argument in action.arguments.items():
+                if not argument.suggest:
+                    continue
+                try:
+                    suggestions = argument.suggest(args, ctx) or []
+                except Exception as error:
+                    answer.setdefault("error", str(error))
+                    continue
+                answer["arguments"][name] = [
+                    {"value": str(s[0]), "label": str(s[1])} if isinstance(s, (tuple, list)) else {"value": str(s)} for s in suggestions
+                ]
+            return answer
+        if method == "feed/watch":
+            feed = self._feeds.get(body.get("feed", ""))
+            if feed is None:
+                raise PluginError(f"no feed called '{body.get('feed')}'")
+            instance = str(body.get("instance", ""))
+            self._watching[instance] = body["feed"]
+            given = dict(body.get("args") or {})
+            filled = {n: (given[n] if str(given.get(n, "")).strip() else a.example) for n, a in feed.arguments.items()}
+            feed.watch(instance, filled, ctx)
+            return {}
+        if method == "feed/unwatch":
+            instance = str(body.get("instance", ""))
+            feed = self._watching.pop(instance, None)
+            prefix = f"{self.id}.@{instance}."
+            with self._lock:
+                for name in [n for n in self._declared if n.startswith(prefix)]:
+                    self._declared.pop(name, None)
+                    self._published.pop(name, None)
+            if feed and self._feeds[feed].unwatch:
+                self._feeds[feed].unwatch(instance, ctx)
+            return {}
+        if method == "settings/changed":
+            self.configure(body.get("settings") or {}, self._data_dir)
+            if self._settings_changed:
+                self._settings_changed(ctx)
+            return {}
+        if method == "shutdown":
+            if self._stop:
+                self._stop(ctx)
+            return {}
+        raise PluginError(f"no method '{method}'")
+
+    def serve(self) -> None:
+        """Speak the protocol on this process's stdin and stdout until the agent goes."""
+        # The protocol is UTF-8 lines ending in a bare newline, whatever the
+        # console's code page; stdout is only the protocol, so a print by habit
+        # goes to the log (stderr) instead.
+        out = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", newline="\n")
+        incoming = io.TextIOWrapper(sys.stdin.buffer, encoding="utf-8")
+        sys.stdout = sys.stderr
+
+        def write(message: Dict[str, Any]) -> None:
+            line = json.dumps(message, separators=(",", ":"), ensure_ascii=False)
+            with self._out_lock:
+                out.write(line + "\n")
+                out.flush()
+
+        self._write = write
+        pool = ThreadPoolExecutor(max_workers=4, thread_name_prefix="flexdeck")
+        started = threading.Event()
+
+        def answer(message: Dict[str, Any]) -> None:
+            method = message["method"]
+            try:
+                result = self.handle(method, message.get("params"))
+                write({"jsonrpc": "2.0", "id": message["id"], "result": result if result is not None else {}})
+            except Exception as error:
+                write({"jsonrpc": "2.0", "id": message["id"], "error": {"code": -32000, "message": str(error)}})
+            if method == "initialize" and not started.is_set():
+                started.set()
+                if self._start:
+                    # After the answer, so a slow connect never counts against the deadline.
+                    def start() -> None:
+                        try:
+                            self._start(self.ctx)
+                        except Exception as error:
+                            self.ctx.log.error(f"start failed: {error}")
+
+                    pool.submit(start)
+            if method == "shutdown":
+                os._exit(0)
+
+        for line in incoming:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                message = json.loads(line)
+            except ValueError:
+                self.ctx.log.error(f"the agent sent something that is not JSON: {line[:200]}")
+                continue
+            if "id" not in message or not message.get("method"):
+                continue
+            if message["method"] in ("initialize", "shutdown"):
+                answer(message)
+            else:
+                pool.submit(answer, message)
+        # The agent closed stdin: it is gone, so follow it.
+        if self._stop:
+            try:
+                self._stop(self.ctx)
+            except Exception:
+                pass
+        os._exit(0)

flexdeck_plugin/__main__.py

@@ -0,0 +1,65 @@
+"""python -m flexdeck_plugin <new|check|pack|verify> [dir]   (also: flexdeck-plugin)"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from . import PluginError, is_valid_id
+from .conformance import conform, describe, find_flexdeck, passed
+from .pack import check, pack
+from .template import scaffold
+
+USAGE = """usage: flexdeck-plugin <command> [dir]
+
+  new <id> ["<Name>"]   a new plugin in ./<id>, ready to test and pack
+  check [dir]           plugin.json and the code agree
+  pack  [dir]           write <id>-<version>.fdpkg, ready to install
+  verify [dir] [--run-actions]
+                        pack, then ask FlexDeck itself whether it will work:
+                        run as the app runs it, checked at every step"""
+
+
+def main(argv=None) -> int:
+    # A console on an old code page shows what it can rather than crashing.
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(errors="replace")
+    args = list(sys.argv[1:] if argv is None else argv)
+    command = args[0] if args else "help"
+    rest = [a for a in args[1:] if not a.startswith("--")]
+    directory = Path(rest[0]) if rest else Path(".")
+    try:
+        if command == "new":
+            if not rest or not is_valid_id(rest[0]):
+                print('usage: flexdeck-plugin new <id> ["<Name>"]   (id: lowercase letters, digits, - and _)', file=sys.stderr)
+                return 1
+            target = scaffold(Path(rest[0]), rest[0], rest[1] if len(rest) > 1 else rest[0])
+            print(f"created {target}\nnext:\n  cd {rest[0]}\n  python -m unittest\n  python -m flexdeck_plugin verify")
+            return 0
+        if command == "check":
+            plugin = check(directory)
+            print(f"{plugin.id} {plugin.version}: plugin.json and the code agree")
+            return 0
+        if command == "pack":
+            packed = pack(directory)
+            print(f"packed {packed.file}\n  {packed.size} bytes\n  sha256 {packed.sha256}")
+            return 0
+        if command == "verify":
+            flexdeck = find_flexdeck(directory)
+            if not flexdeck:
+                print("verify asks FlexDeck itself, and none was found. Install the FlexDeck app, or set FLEXDECK_BIN to its executable.", file=sys.stderr)
+                return 1
+            packed = pack(directory)
+            report = conform(packed.file, flexdeck, run_actions="--run-actions" in args)
+            print(describe(report))
+            return 0 if passed(report) else 1
+    except (PluginError, RuntimeError) as error:
+        print(f"flexdeck-plugin: {error}", file=sys.stderr)
+        return 1
+    print(USAGE)
+    return 0 if command in ("help", "--help", "-h") else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

flexdeck_plugin/conformance.py

@@ -0,0 +1,73 @@
+"""Will this plugin work in FlexDeck? Asked of FlexDeck itself.
+
+``flexdeck-plugin verify`` packs the plugin and hands it to the FlexDeck on
+this computer (``flexdeck verify-plugin``), which runs it exactly as it would
+after an install (the same host, deadlines and rules) and checks it at every
+step. Nothing here re-implements those rules, so they cannot drift from the
+app's; the TypeScript SDK asks the same way.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Mapping, Optional
+
+EXE = "flexdeck.exe" if os.name == "nt" else "flexdeck"
+
+
+def find_flexdeck(start: Optional[Path] = None, env: Optional[Mapping[str, str]] = None) -> Optional[str]:
+    """FLEXDECK_BIN; a build in a FlexDeck checkout above ``start``; the PATH; where the app installs."""
+    env = os.environ if env is None else env
+    if env.get("FLEXDECK_BIN"):
+        return env["FLEXDECK_BIN"] if Path(env["FLEXDECK_BIN"]).is_file() else None
+    here = Path(start or Path.cwd()).resolve()
+    for directory in [here, *here.parents]:
+        for build in ("debug", "release"):
+            candidate = directory / "target" / build / EXE
+            if candidate.is_file():
+                return str(candidate)
+    on_path = shutil.which("flexdeck", path=env.get("PATH"))
+    if on_path:
+        return on_path
+    if os.name == "nt":
+        installed = [Path(env[k]) / "flexdeck" / EXE for k in ("LOCALAPPDATA", "ProgramFiles") if env.get(k)]
+    elif sys.platform == "darwin":
+        installed = [Path("/Applications/flexdeck.app/Contents/MacOS/flexdeck")]
+    else:
+        installed = [Path("/usr/bin/flexdeck"), Path("/usr/local/bin/flexdeck")]
+    return next((str(p) for p in installed if p.is_file()), None)
+
+
+def conform(package: Path, flexdeck: str, run_actions: bool = False) -> dict:
+    """Ask ``flexdeck`` whether the package (a .fdpkg or a package folder) will work."""
+    with tempfile.TemporaryDirectory(prefix="flexdeck-verify-") as scratch:
+        out = Path(scratch) / "report.json"
+        args = [flexdeck, "verify-plugin", str(Path(package).resolve()), "--out", str(out)]
+        if run_actions:
+            args.append("--run-actions")
+        run = subprocess.run(args, capture_output=True, text=True, timeout=120)
+        if not out.is_file():
+            raise RuntimeError(f"{flexdeck} could not verify it: {(run.stderr or 'no report').strip()}")
+        return json.loads(out.read_text(encoding="utf-8"))
+
+
+def passed(report: dict) -> bool:
+    return all(check["ok"] for check in report["checks"])
+
+
+def describe(report: dict) -> str:
+    lines = [f"{report['plugin']} ({report['runtime']})"]
+    for check in report["checks"]:
+        lines.append(("  ok  " if check["ok"] else "  FAIL") + f"  {check['name']}" + (f" — {check['detail']}" if check["detail"] else ""))
+    failed = sum(1 for check in report["checks"] if not check["ok"])
+    if failed == 0:
+        lines += ["", "It will work in FlexDeck."]
+    else:
+        lines += ["", f"{failed} check{'' if failed == 1 else 's'} failed: fix {'it' if failed == 1 else 'them'} before anyone installs it."]
+    return "\n".join(lines)

flexdeck_plugin/pack.py

@@ -0,0 +1,109 @@
+"""Package a plugin: ``<id>-<version>.fdpkg``, ready to install.
+
+The package carries the plugin's own Python files and this SDK beside them, so
+it runs on any Python 3.10+ with nothing installed. ``plugin.json`` and the
+code must agree on who the plugin is (the agent refuses a plugin whose answer
+differs from its package), so that is checked first.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import json
+import os
+import sys
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+from . import ABI_VERSION, Plugin, PluginError, is_valid_id
+
+SDK_DIR = Path(__file__).resolve().parent
+#: Never packed: tests, caches, packages, environments, and a copy of the SDK
+#: (the one running this is packed instead).
+SKIP_DIRS = {"__pycache__", "tests", "test", ".venv", "venv", "dist", "build", ".git", ".pytest_cache", "flexdeck_plugin"}
+PACKED = (".py", ".json", ".txt", ".md", ".png", ".svg")
+
+
+@dataclass
+class Packed:
+    file: Path
+    size: int
+    sha256: str
+
+
+def read_package(directory: Path) -> dict:
+    path = directory / "plugin.json"
+    if not path.is_file():
+        raise PluginError(f"no plugin.json in {directory}")
+    package = json.loads(path.read_text(encoding="utf-8"))
+    problems = []
+    if package.get("runtime") != "python":
+        problems.append('runtime must be "python"')
+    if package.get("abi") != ABI_VERSION:
+        problems.append(f"abi must be {ABI_VERSION}")
+    if not is_valid_id(str(package.get("id", ""))):
+        problems.append("id: lowercase letters, digits, - and _, starting with a letter")
+    entry = package.get("entry")
+    if not entry or not (directory / entry).is_file():
+        problems.append(f"entry: '{entry}' is not a file in the plugin")
+    if problems:
+        raise PluginError("plugin.json: " + "; ".join(problems))
+    return package
+
+
+def load_plugin(directory: Path, entry: str) -> Plugin:
+    """Import the entry file (without serving it) and find its Plugin."""
+    sys.path.insert(0, str(directory))
+    try:
+        spec = importlib.util.spec_from_file_location("_flexdeck_entry", directory / entry)
+        module = importlib.util.module_from_spec(spec)
+        assert spec.loader is not None
+        spec.loader.exec_module(module)
+    finally:
+        sys.path.remove(str(directory))
+    found = [value for value in vars(module).values() if isinstance(value, Plugin)]
+    if len(found) != 1:
+        raise PluginError(f"{entry} should define exactly one Plugin; it defines {len(found)}")
+    return found[0]
+
+
+def check(directory: Path) -> Plugin:
+    """plugin.json and the code agree, as the agent will require."""
+    directory = Path(directory).resolve()
+    package = read_package(directory)
+    plugin = load_plugin(directory, package["entry"])
+    for key, value in (("id", plugin.id), ("name", plugin.name), ("version", plugin.version)):
+        if package.get(key) != value:
+            raise PluginError(f"plugin.json says {key} '{package.get(key)}', the code says '{value}'")
+    extra = sorted(set(plugin.permissions) - set(package.get("permissions", [])))
+    if extra:
+        raise PluginError(f"the code asks for {', '.join(extra)}, which plugin.json does not declare")
+    return plugin
+
+
+def _files(directory: Path) -> List[Path]:
+    files = []
+    for root, dirs, names in os.walk(directory):
+        dirs[:] = sorted(d for d in dirs if d not in SKIP_DIRS and not d.startswith("."))
+        for name in sorted(names):
+            if name.endswith(PACKED):
+                files.append(Path(root) / name)
+    return files
+
+
+def pack(directory: Path, out: Optional[Path] = None) -> Packed:
+    directory = Path(directory).resolve()
+    check(directory)
+    package = read_package(directory)
+    target = Path(out) if out else directory / f"{package['id']}-{package['version']}.fdpkg"
+    with zipfile.ZipFile(target, "w", zipfile.ZIP_DEFLATED) as archive:
+        for path in _files(directory):
+            archive.write(path, path.relative_to(directory).as_posix())
+        for path in sorted(SDK_DIR.rglob("*")):
+            if path.is_file() and "__pycache__" not in path.parts and path.suffix in (".py", ".json"):
+                archive.write(path, "flexdeck_plugin/" + path.relative_to(SDK_DIR).as_posix())
+    data = target.read_bytes()
+    return Packed(file=target, size=len(data), sha256=hashlib.sha256(data).hexdigest())

flexdeck_plugin/template.py

@@ -0,0 +1,134 @@
+"""The plugin ``flexdeck-plugin new`` writes: every part used once, tested, packable."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+PLUGIN = '''"""NAME: a FlexDeck plugin.
+
+    python -m unittest                    run its tests, without FlexDeck
+    python -m flexdeck_plugin verify      ask FlexDeck itself whether it will work
+    python -m flexdeck_plugin pack        write ID-0.1.0.fdpkg, ready to install
+
+Everything a plugin can declare is used once below. Delete what you do not need.
+"""
+
+from flexdeck_plugin import Plugin, arg
+
+# The id is the namespace for everything this plugin owns: its values are
+# `ID.<name>`, and a key's action says plugin "ID". It must match plugin.json
+# and can never change once people use it.
+plugin = Plugin(
+    id="ID",
+    name="NAME",
+    version="0.1.0",
+    description="A starting point for a FlexDeck plugin.",
+    author="you",
+    # Shown before anyone installs it. Ask only for what you use.
+    permissions=["notifications"],
+)
+
+# Configuration filled in once. A secret is never shown again once saved.
+plugin.setting("greeting", "text", "The word to greet with", default="Hello")
+
+# Live values a key can show and an automation can react to.
+plugin.variable("ID.greetings", "number", "How many greetings so far")
+
+# Things that happen, which an automation can be started by.
+plugin.event("greeted", "Someone was greeted", fields=["name"])
+
+
+# Every argument has an example that works: the editor fills it in, and the
+# tests and `verify` run every action with it.
+@plugin.action("greet", "Greet someone", {"name": arg("text", "world", "Who to greet")})
+def greet(args, ctx):
+    count = (ctx.vars.get("ID.greetings") or 0) + 1
+    ctx.vars.set({"ID.greetings": count})
+    ctx.emit("greeted", {"name": args["name"]})
+    ctx.notify(f"{ctx.settings['greeting']}, {args['name']}!")
+
+
+# Asked only for values something is showing.
+@plugin.sample
+def sample(wanted, ctx):
+    return {"ID.greetings": ctx.vars.get("ID.greetings") or 0}
+
+
+# A feed: values each key gets for itself, with its own arguments. A key
+# reads them as {{this.word}}.
+@plugin.feed("shout", "A word, louder", fields={"word": "text"}, arguments={"word": arg("text", "hello", "The word")})
+def shout(instance, args, ctx):
+    ctx.feed(instance).set({"word": args["word"].upper() + "!"})
+
+
+# A ready-made key for the gallery.
+plugin.preset(
+    "shout",
+    "Shout",
+    {"sources": [{"source": "ID/shout"}], "face": {"layout": "FACE_LAYOUT_VALUE", "elements": [{"slot": "SLOT_VALUE", "template": "{{this.word}}"}]}},
+    category="Plugins",
+    description="A word, louder.",
+)
+
+if __name__ == "__main__":
+    plugin.serve()
+'''
+
+TEST = '''import unittest
+
+from flexdeck_plugin.testing import Harness, check_definition
+
+from plugin import plugin
+
+
+class NAMEClassTest(unittest.TestCase):
+    def test_flexdeck_would_accept_the_definition(self):
+        self.assertEqual(check_definition(plugin), [])
+
+    def test_greeting_counts_and_announces(self):
+        host = Harness(plugin, settings={"greeting": "Hi"})
+        self.assertTrue(host.invoke("greet", {"name": "ada"})["ok"])
+        self.assertEqual(host.value("ID.greetings"), 1)
+        self.assertEqual(host.sent("event/emit"), [{"event": "greeted", "payload": {"name": "ada"}}])
+        self.assertEqual(host.sent("notify")[0]["title"], "Hi, ada!")
+
+    def test_a_feed_publishes_under_its_key(self):
+        host = Harness(plugin)
+        host.watch("shout", "w1", {"word": "hey"})
+        self.assertEqual(host.value("ID.@w1.word"), "HEY!")
+
+
+if __name__ == "__main__":
+    unittest.main()
+'''
+
+
+def scaffold(target: Path, id: str, name: str) -> Path:
+    """Write a new plugin into ``target`` (which must not exist)."""
+    target = Path(target)
+    if target.exists():
+        raise FileExistsError(f"{target} already exists")
+    (target / "tests").mkdir(parents=True)
+    class_name = "".join(part.capitalize() for part in id.replace("-", "_").split("_")) or "Plugin"
+    fill = lambda text: text.replace("NAMEClass", class_name).replace("ID", id).replace("NAME", name)  # noqa: E731
+    (target / "plugin.py").write_text(fill(PLUGIN), encoding="utf-8")
+    (target / "tests" / "__init__.py").write_text("", encoding="utf-8")
+    (target / "tests" / "test_plugin.py").write_text(fill(TEST), encoding="utf-8")
+    package = {
+        "abi": 4,
+        "id": id,
+        "name": name,
+        "version": "0.1.0",
+        "description": "A starting point for a FlexDeck plugin.",
+        "author": "you",
+        "runtime": "python",
+        "entry": "plugin.py",
+        "permissions": ["notifications"],
+    }
+    (target / "plugin.json").write_text(json.dumps(package, indent=2) + "\n", encoding="utf-8")
+    (target / "README.md").write_text(
+        f"# {name}\n\nA FlexDeck plugin.\n\n    python -m unittest\n    python -m flexdeck_plugin verify\n    python -m flexdeck_plugin pack\n",
+        encoding="utf-8",
+    )
+    return target

flexdeck_plugin/testing.py

@@ -0,0 +1,91 @@
+"""Test a plugin without the agent: the host's side of the conversation, in process.
+
+    from flexdeck_plugin.testing import Harness, check_definition
+    from plugin import plugin
+
+    def test_every_action_accepts_its_examples():
+        assert check_definition(plugin) == []
+
+    def test_toggle():
+        host = Harness(plugin)
+        assert host.invoke("toggle")["ok"]
+        assert host.value("lights.on") is True
+
+For the whole picture (run as FlexDeck runs it), ``flexdeck-plugin verify``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Optional
+
+from . import ABI_VERSION, KINDS, Plugin
+
+
+class Harness:
+    """Plays the agent: ``initialize`` first, then whatever a test asks."""
+
+    def __init__(self, plugin: Plugin, settings: Optional[Mapping[str, str]] = None, data_dir: Optional[str] = None) -> None:
+        self.plugin = plugin
+        plugin.sent.clear()
+        self.introduction = plugin.handle("initialize", {"abi": ABI_VERSION, "settings": dict(settings or {}), "dataDir": data_dir})
+
+    def invoke(self, action: str, args: Optional[Mapping[str, str]] = None) -> Dict[str, Any]:
+        return self.plugin.handle("invoke", {"action": action, "args": dict(args or {})})
+
+    def check(self, action: str, args: Optional[Mapping[str, str]] = None) -> Dict[str, Any]:
+        return self.plugin.handle("check", {"action": action, "args": dict(args or {})})
+
+    def sample(self, wanted: List[str]) -> Dict[str, Any]:
+        return self.plugin.handle("sample", {"wanted": list(wanted)})["values"]
+
+    def watch(self, feed: str, instance: str = "test", args: Optional[Mapping[str, str]] = None) -> None:
+        self.plugin.handle("feed/watch", {"instance": instance, "feed": feed, "args": dict(args or {})})
+
+    def unwatch(self, instance: str = "test") -> None:
+        self.plugin.handle("feed/unwatch", {"instance": instance})
+
+    def value(self, name: str) -> Any:
+        """The last value published for ``name``, as the host would hold it."""
+        found = None
+        for message in self.plugin.sent:
+            if message["method"] == "vars/set" and name in message["params"]["values"]:
+                found = message["params"]["values"][name]["value"]
+        return found
+
+    def sent(self, method: str) -> List[Dict[str, Any]]:
+        return [m["params"] for m in self.plugin.sent if m["method"] == method]
+
+
+def check_definition(plugin: Plugin) -> List[str]:
+    """Problems FlexDeck would find in the definition: arguments without a
+    working example, values outside the namespace, actions that refuse their
+    own examples. Empty: none."""
+    problems: List[str] = []
+    manifest = plugin.manifest()
+    owners = [(a["action"], a["arguments"]) for a in manifest["actions"]] + [(f["name"], f["arguments"]) for f in manifest.get("feeds", [])]
+    for owner, arguments in owners:
+        for argument in arguments:
+            where = f"{owner}.{argument['name']}"
+            example = argument["example"]
+            if argument["kind"] not in KINDS:
+                problems.append(f"{where}: '{argument['kind']}' is not a kind")
+            elif not example:
+                if not argument["optional"]:
+                    problems.append(f"{where} has no example")
+            elif argument["kind"] == "number":
+                try:
+                    float(example)
+                except ValueError:
+                    problems.append(f"{where}: '{example}' is not a number")
+            elif argument["kind"] == "bool" and example not in ("true", "false"):
+                problems.append(f"{where}: '{example}' is not true or false")
+    for variable in plugin.variables():
+        if not variable["name"].startswith(f"{plugin.id}."):
+            problems.append(f"{variable['name']} is not under {plugin.id}.")
+    host = Harness(plugin)
+    for action in manifest["actions"]:
+        args = {a["name"]: a["example"] for a in action["arguments"] if a["example"]}
+        answer = host.check(action["action"], args)
+        if not answer["ok"]:
+            problems.append(f"{action['action']} refuses its own examples: {answer.get('error')}")
+    return problems