silverbulletmd
Make plugs more explicitly define settings
Right now various plugs implicitly read values from SETTINGS possibly documenting them, possibly not. It would be nicer if plugs can explicitly define their settings as well as their schema (at least their type). Same for SECRETS I suppose.
Not only is this better for documentation, it would also enable building a automatically generated proper settings UI listing all settings, changing them etc. Something more intuitive than YAML in a page.
Not sure how this should be specified yet, one way would be to extend the .plug.yaml format at the PlugOS level, something along the lines of:
name: core
settings:
initPage:
type: string
default: index
description: Specifies the first page to load when loading your space
weeklyNoteTemplate:
type: string
default: template/Weekly Note
functions:
# …
The type field may need to be something along the lines of JSON schema maybe to allow more complex settings. For instance, the silverbullet-mattermost plug uses more complicated values for settings (using a single mattermost key with a mapping of server names to URLs etc.)
Another idea here would be to “auto scope” settings by plug name. So to use the previous core example, in SETTINGS values would be defined with:
core:
initPage: index
weeklyNoteTemplate: My Weekly Note
Then we don’t have to worry about name clashes between plugs.
Not digged into the code actually, so say if this won't work, but my thoughts are:
- require a scheme for all plugs (use zod or valibot
- parse the provided schema (not allowing extra fields), and provide the plug this (validated) object
- plugs cannot directly access the setting (there could be secrets anyway)
This way plugs declaratively state what settings they require.
You can combine this setup with autoscoping.
There could be dependant plugs, so one may want to allow to dig in other plugs settings though...
We would need some kind of serializable scheme, because we need to pass from a webworker. But I like the idea of silverbullet providing it, because every plug that uses settings is going to need some validation. No point in having 10 zod instances in 10 webworkers, that's just dead weight on the plug bundles. I think using JSON-Schema here would be sensible as it seems to be standardized. There are also seem to be implementations of it.
Theoretically, we could just put it into the manifest as json is fully representable in yaml (a bit like you proposed above, which I didn’t read before lol). This would be very simple. The only missing thing to handle would be typescript support.