Plugin format

What a plugin's source folder, its bundle and a release's index of bundles hold, and the commands that check and build them.

A plugin is written as a source folder, built into a bundle that installs it, and listed with other bundles in a release's index. Install a plugin installs one. The CLI checks and builds them with no server.

Source folder

tickets/
  plugin.json
  types/
    common.ticket.json
    common.ticket.md
  edge-types/
    blocks.json
  • plugin.json holds the identity fields below, and an optional connector object. It names no version: a release stamps one from its tag, and marfa plugins check refuses a version here.
  • types/<id>.json holds a type definition, as Type definition describes. <id>.md beside it is the type's guidance, at most 1,000 characters.
  • edge-types/<id>.json holds an edge type, as Register an edge type takes it.
  • A file not named after its id is refused file_name_mismatch, in the check, the bundle and the install alike.

A type sits under common or a root of the plugin's own. One under core, system, marfa, app or user is refused 403 forbidden. A type's parent outside the plugin is one Marfa ships, a common type, or a type the installer may write.

Identity fields

plugin.json and the bundle hold each of these, and the bundle carries them as they are:

FieldRule
nameLowercase words and numbers joined by hyphens, starting with a word, at most 64 characters, such as tickets.
titleThe name people see, at most 100 characters.
descriptionWhat the plugin adds, in a sentence, at most 300 characters.
markAn icon ID, as a type's display hints take one, such as lucide:ticket.
makerWho made the plugin, at most 64 characters.
marfaThe oldest Marfa release it works with, such as 0.0.92. A later release than the server's is refused 409 plugin_needs_newer_server.

Bundle

marfa plugins bundle <folder> --version 1.2.0 writes <name>.plugin.json in the current folder, or the one --output names. The bundle is one JSON object with format set to 1, the identity fields, and:

FieldHolds
versionThe plugin's version, such as 1.2.0; 0.0.0 without --version.
typesEach type definition, with its .md file as guidance.
edge_typesEach edge type.
connectorThe connector object from plugin.json, if it names one.

A bundle with any other field is refused 400 validation_error. The instance records the SHA-256 of the bundle's bytes as the plugin's fingerprint, so build a release once and install the same file everywhere. Install a plugin lists every answer.

Connector

The connector object describes the connector the plugin brings, which a connector host runs. Installing a plugin with one needs connectors.manage, and a field it doesn't define is refused 400 validation_error, naming its path.

FieldRule
sourceRequired. The source its key holds, 1 to 200 characters with no whitespace at either end, not . or .., and not starting with oauth:, restored: or connector-host:. One source belongs to one plugin: one another plugin or a registration holds is refused 409 connector_source_held, and a newer version must keep it.
source_nameRequired. The source's name people see, at most 100 characters.
source_markAn icon ID for the source.
kindsRequired, at least one. Each kind of record it brings: name (lowercase letters, digits and underscores), type (one of the bundle's types), direction (in, out or both), and an optional default_mapping that sets only tier, status_overrides and fields on that type, as a mapping does.
edge_typesThe edge types it writes, each named once: the bundle's own, or ones Marfa ships whose ends aren't system types, such as attached-to. Any other is refused 400 validation_error. Its key writes each, and a newer version may drop one.
settingsEach setting it reads: name, label, kind (text, number, boolean or choice), required, and optionally secret (text only), default (of its kind, never on a secret) and choices (a choice setting only).
sign_inFor a connector that signs in: kind oauth2, provider google, scopes, and the settings that hold the client ID, the client secret and the token, the last two secret.
runsRequired. { "on": "host" }.

Release index

marfa plugins index <folder> writes plugins.json beside the bundles in a folder. marfa plugins install <name> reads it from a release to find a bundle and check its bytes. WithMarfa publishes its plugins as a GitHub Release of withmarfa/plugins for each version, holding every plugin's bundle, plugins.json and checksums.txt, with build provenance:

FieldHolds
format1.
pluginsOne entry for each bundle: its identity fields, version, has_connector, bundle (the file name) and sha256.

Check a folder

marfa plugins check <folder> judges a folder as installing it would, with no server: plugin.json, each type as marfa types check judges one but with common types taken and the roots above refused, and each edge type against Marfa's own and the folder's. It exits 1 with each problem and its path.

The rules behind this page are in the plugins chapter of the contract, and the CLI chapter holds the commands'.

On this page