fylr-build-plugin

command module
v1.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 9, 2026 License: Unlicense Imports: 22 Imported by: 0

README

fylr-build-plugin

The build driver for fylr plugins — the "make" that knows how a fylr plugin is put together. This README is also the reference for how a fylr plugin repository is structured and what a plugin can offer; the living example is fylr-plugin-example, which exercises every feature described here. Start a new plugin by copying its structure.

The tool is distributed as a versioned Go module, so a plugin repo carries no build machinery (no submodule, no vendored Makefile include):

go run github.com/programmfabrik/fylr-build-plugin@latest build

Plugin repos keep a thin Makefile shim for muscle memory (make build, make zip, …) that just calls the tool.

Versioning: plugins call the tool with @latest, which resolves the newest tagged release — a v1.0.1 reaches every plugin build automatically, no plugin repo is touched. main can hold unfinished work; cutting a release is pushing a vX.Y.Z tag. An incompatible change is released as a new major version, which per Go's semantic import versioning gets a new module path (github.com/programmfabrik/fylr-build-plugin/v2) — existing plugins keep resolving the v1 line untouched and migrate by changing the one go run line when they choose to.

The name follows the fylr convention: fylr-plugin-* is reserved for plugins, tooling is named fylr-<verb>-plugin — this one builds plugins. It also seals them: the former fylr-seal-plugin is merged in here, including the pluginseal package that fylr imports to open sealed plugins.

A well-structured fylr plugin

One repo per plugin, named fylr-plugin-<name> (custom data types: custom-data-type-<type>). fylr plugins are fylr-only: no easydb5 hybrid code, and easydb-library must never be used.

Start a new plugin with fylr-build-plugin init in a fresh repo directory — it scaffolds everything below (a buildable plugin with one example API extension, webfrontend and loca) and refuses to run inside an existing plugin. Existing files (a GitHub-created README.md, LICENSE, …) are kept and skipped.

fylr-plugin-example/
├── manifest.yml          the plugin: identity + every feature wiring, read by
│                         fylr — ships VERBATIM as build/<name>/manifest.yml
├── build.yml             the build: explicit delivery lists for fylr-build-plugin
├── Makefile              thin shim: make help/build/zip/seal/loca/check/clean
├── README.md             plugin docs; the zip ships a self-contained copy
├── LICENSE
├── .github/workflows/
│   └── release.yaml      release build, from templates/ (public or private)
├── .gitignore            build/, compiled JS, .DS_Store — generated files are
│                         NEVER committed, dev and CI compile from source
├── l10n/
│   └── example-loca.csv  localization, mastered in Google Sheets ("fylr
│                         localization" sheet, one tab per plugin), pulled
│                         with `make loca` — never edited by hand
├── server/               server-side programs (node / python3 / Go), wired in
│                         the manifest as extensions and callbacks
│   └── extension/hello/  a Go module: cross-compiled by the build, sources
│                         never ship
├── fas_config/           asset-server config: cookbooks + produce config
├── webfrontend/          frontend sources and assets (= base_url_prefix)
│   ├── *.coffee          compiled into the plugin.webfrontend.url bundle
│   ├── lib/*.js          vendored JS, a source of that same bundle
│   ├── *.scss            compiled to same-named .css
│   └── *.css/.html/img   delivered as-is (build.yml webfrontend.install)
└── build/                generated by `build`, gitignored:
    └── fylr_example/     the plugin as fylr loads it — manifest.yml,
                          build-info.json, compiled JS/CSS/binaries, copies

The folder build/<plugin.name>/ is the plugin in its installed form: fylr loads it directly from disk during development, and the release zip is exactly this tree (top-level folder = plugin.name, which fylr enforces on install — the name comes from the manifest, not the repo).

What a fylr plugin can offer

Every feature is declared in manifest.yml; the example's manifest exercises all of them. Server-side programs are wired the same way everywhere: fylr runs them via its exec services (node, python3, or exec for compiled binaries), passing the request on stdin and reading the response from stdout; %_exec.pluginDir% resolves to the installed plugin folder, %info.json% passes fylr config + call context, and %_exec.GOOS% / %_exec.GOARCH% select the right cross-compiled binary. A callback can run with an api token (plugin_user) to call back into the fylr API.

Manifest section Feature
plugin identity: name, version, displayname, plus the l10n CSV and the webfrontend entry points (url JS bundle, css, html)
base_url_prefix where the webfrontend files are served from (by convention the webfrontend/ folder)
extensions plugin API endpoints served under fylr's API, each backed by an exec program
callbacks hooks into fylr flows: db_pre_save (an ordered steps list with objecttype filters — validate or modify objects before save), transition_db_pre_save, export, export_transport
collection_upload hooks into collection uploads (api / hotfolder), with per-hook config parameters
base_config plugin settings that appear in fylr's base config UI and /api/config, typed parameters
system_rights plugin-defined system rights with typed parameters (bool, int, text, string-list*, mask-select, objecttype-select, eas-column-select, pool-select, preview-versions)
custom_types custom data types: index mapping (text, number, geo, …, incl. skipTerms), per-schema/mask config, and a batched update callback
fas_config asset production: a produce config and cookbooks merged into the fylr asset server
custom_events plugin-defined event types

Localization: the plugin.l10n CSV has a key column and one column per language (de-DE, en-US, …); extra sheet columns (fil, the R TODO checkboxes) are ignored by fylr's loader, so the Google Sheets export is committed as-is.

Next to the manifest, the build writes build-info.json (repository, rev, release, lastchanged, builddate) — fylr's plugin manager shows it, so an installed plugin is traceable to a commit and release.

Commands

Command Does
init scaffold a new plugin into the current (fresh) directory
build assemble build/<plugin.name>/ — loadable by fylr from disk
zip build + release zip
seal seal a plugin zip for the marketplace (public key only)
genkey generate a seal recipient keypair
info inspect a (sealed) plugin zip: name, sealed?, recipient
loca pull loca CSV(s) from their Google Sheets master
readme write a self-contained README (relative images inlined)
check validate the build tree against the manifest
clean remove the build folder

All commands run from the plugin repo root (where manifest.yml lives). External tools are checked per step with an actionable error: coffee is only required when the plugin has CoffeeScript, sass only for SCSS, go only for Go server extensions, uv only for Python packages.

The tool reads no environment variables — every input is a flag. Where a release workflow has a value in env (RELEASE_TAG), the plugin's Makefile shim translates it into the -release flag.

How the release zip is named

The zip is always build/<repo>.zip, named after the repository. This is a rule of the tool, hard-wired: there is no flag, no env var and no per-repo exception.

A release url then reads as one piece, and can be written down without looking anything up:

https://github.com/programmfabrik/<repo>/releases/latest/download/<repo>.zip

The manifest's plugin.name is deliberately not used. The two diverge often enough — fylr-plugin-scancode-display ships the plugin fylr-scancode-display, fylr-plugin-custom-data-type-k10plus ships custom-data-type-gvk — that a manifest-derived asset would sit at a url that disagrees with itself. plugin.name is also editable in a way the repository is not: renaming it would silently move the release asset.

Inside the zip the top-level folder stays the plugin name, which fylr requires; it is unaffected by the name of the file it arrives in.

The repository is taken from the origin remote, falling back to the directory name. The shipped release workflows attach build/*.zip, so they never restate the rule.

What build does

The delivered files are listed explicitly in build.yml — nothing is derived from the manifest, since a derived list is easily incomplete. The safety net is check, which runs with every build and validates the assembled tree against every path the manifest references — a dangling reference is reported as a warning (it can be deliberate, e.g. the example plugin's missing-module test callbacks).

  • manifest.yml is copied verbatim to build/<name>/manifest.yml (no master/generated split; plugin.name in the manifest names the build folder and the zip's top-level dir, which fylr enforces on install).

  • server.install and webfrontend.install entries (files or dirs) are copied verbatim. .DS_Store, .gitignore, .git, node_modules never ship.

  • server.bundles and webfrontend.bundles entries are assembled: sources concatenated in the order written, each handled by its extension (.coffee compiled with CoffeeScript 1.x — the version the plugins are stuck on — .scss compiled, anything else verbatim). A webfrontend entry without out writes plugin.webfrontend.url, the only bundle fylr loads, so a vendored library that is not CoffeeScript (a viewer, a charting lib) has to be part of it — delivered next to the bundle it would never be loaded.

  • webfrontend.scss files compile to same-named .css.

  • npm dependencies of the plugin's node programs are resolved into the delivered files: every %_exec.pluginDir%/….js the manifest runs has its requires followed and the reached modules inlined, node's builtins left alone. Nothing configures this — declare the dependency in package.json, commit package-lock.json, and the build runs npm ci when needed. node_modules never ships, so this is what makes a dependency work at all; a program that requires nothing is delivered byte-for-byte as written.

  • Python packages of the plugin's python3 programs are listed in build.yml, per folder:

    server:
      python:
        - dir: server/extension/python_dep   # delivered by server.install
          packages:                          # as pip takes them, "trimesh>=4" too
            - python-slugify
            - trimesh
    

    The build resolves them with uv for the fylr image — Python 3.14 on Linux, whatever machine builds, so a dependency behind a marker like python_version >= "3.13" is decided the way it is on the instance — and installs every resolved package, dependencies included, into that folder of the build tree. Python looks into a program's own folder first, so the programs there import them without any setup; a program in another folder does not see them. Nothing runs pip on an instance or an execserver: the packages travel in the zip, with their .dist-info, which records the version that shipped.

    Only pure-Python packages ship. A compiled one is built for one Python and one platform, and the image's Python moves with Debian, so compiled packages come from the fylr image, which installs them explicitly: numpy and opencv-python. They are resolved capped at the version the image has, so a dependency that needs a newer one fails the build, and any other compiled package fails it too — it has to be added to the fylr image first. A fylr outside the image (a developer's own) runs the programs with its own python3, which then needs a version the packages accept (Requires-Python) and those compiled packages installed.

  • server.go.modules cross-compile for every configured arch (CGO off, trimmed, stripped) into their exe template — %GOOS%/%GOARCH% replaced, matching the manifest's %_exec.GOOS%/%_exec.GOARCH% references. Go sources do not ship.

  • build-info.json is written beside the manifest: repository, rev, release (from -release; the release workflow's tag reaches the tool via the Makefile), lastchanged, builddate.

  • check runs automatically: every manifest reference (%_exec.pluginDir%/... exec programs, plugin.l10n, plugin.webfrontend.*, fas_config files) should exist in the build tree; cross-compiled references are checked for every configured arch, commented-out manifest blocks do not count. Missing references are warnings, not errors.

Development loop

build produces an on-disk plugin. In the fylr server's fylr.yml:

plugin:
    paths+:
        - ../my-plugin/build

Point at build/, not the repo root — fylr walks the path for any manifest.yml, and the root manifest would collide with the built one.

build.yml

The explicit build description. Unknown keys are rejected. Every feature is exercised by fylr-plugin-example's build.yml.

server:                  # the non-webfrontend side: l10n and fas_config too
  install:               # server-side delivery, copied verbatim
    - server
    - fas_config
    - l10n
  bundles:               # assembled server-side files (see Bundles below)
    - out: updater/DANTEUpdater.js
      sources:
        - src/updater/DANTEUpdater.js
        - webfrontend/DANTEUtil.coffee
  go:                    # Go server extensions, cross-compiled
    archs:               # each entry sets Go's GOOS/GOARCH build env;
      - { GOOS: linux, GOARCH: amd64 }   # optional — default: every
      - { GOOS: darwin, GOARCH: arm64 }  # platform fylr runs on
    modules:
      - dir: server/extension/hello
        exe: server/extension/hello/hello-%GOOS%-%GOARCH%.exe

webfrontend:
  bundles:               # no out -> plugin.webfrontend.url, the bundle fylr
    - sources:           # loads; sources in the order written
        - webfrontend/lib/vendor.js       # verbatim
        - webfrontend/MyClass.coffee      # compiled (CoffeeScript 1.x)
        - webfrontend/UsesMyClass.coffee
  scss:                  # compiled to same-named .css
    - webfrontend/MyStyle.scss
  l10n_json:             # loca CSV -> per-culture JSONs the webfrontend
    - csv: l10n/my-loca.csv       # loads (easydb-library l10n2json format),
      out: l10n                   # written under base_url_prefix (default l10n)
  install:               # delivered as-is: plain css, html, images, fonts
    - webfrontend/MyPlugin.html
    - webfrontend/MyPlugin.css

loca:                    # Google Sheets masters for the loca command
  - csv: l10n/my-loca.csv
    sheet: <spreadsheet key>
    gid: "<tab gid>"

zip_aliases:             # historical asset names (see below)
  - customDataTypeDante.zip
Bundles

A bundle is one file assembled from an ordered list of sources. Every file a plugin ships runs in one of two places, so bundles are declared on that side: server.bundles for what node runs (and for l10n, which is delivered there too), webfrontend.bundles for browser code. A webfrontend entry may leave out empty, meaning plugin.webfrontend.url — the common case then does not restate a path the manifest already owns. The sides are validated against base_url_prefix, so a bundle cannot land on the wrong one by accident.

Sources are concatenated in the order written, each handled by its extension (.coffee and .scss compiled, anything else verbatim), and two sources are never glued together — a source not ending in a newline gets one.

Order being the author's matters: the custom-data-type updaters need a hand-written Node script first with the shared utility appended, while a plugin vendoring a library may need it evaluated before its own code.

out is any path inside the plugin folder, so a bundle is not limited to JavaScript — it also covers concatenating several CSS files into the one the manifest declares, or appending a second CSV to an l10n file. Bundles run after install, so a bundle may overwrite a file that was copied in verbatim.

npm dependencies

node_modules never ships. A require("pg") in a server program therefore has nothing to resolve against on the instance, which is why the build resolves it at build time: for every node program the manifest runs (%_exec.pluginDir%/….js), the requires are followed from that file and the reached modules are inlined into it, while node's builtins stay real requires.

There is no key for this. Declare the dependency in package.json and commit package-lock.json; the build installs (npm ci) when node_modules is missing or older than the lockfile. It applies to assembled files too — an updater built by server.bundles is a node program like any other. A file whose module graph is only itself is left exactly as delivered.

Native modules (node-gyp: pg-native, sharp) cannot be bundled and are host-specific — a plugin must not depend on them. An unresolvable require fails the build rather than shipping a program that dies on its first call.

Historical asset names

A published asset name can never be retired, only added to. fylr updates a url plugin by re-fetching the url it stored at install time — not by re-reading the marketplace catalog — so an instance that installed while the zip had a different name holds that url forever. Dropping the name breaks its updates silently, and the instance has no way to discover the new one.

Any repo whose asset name has changed — every plugin migrated here from a hand-written Makefile, which named its zip whatever it liked — lists its previous names and keeps publishing them:

zip_aliases:
  - customDataTypeDante.zip

zip writes each alias as a byte-identical copy beside the real zip. The release workflows attach build/*.zip, so the copies reach the release without the workflow having to know they exist.

Loca

Plugin loca CSVs are mastered in Google Sheets (fylr's "fylr localization" sheet, one tab per plugin) and pulled with fylr-build-plugin loca — never edited locally. The raw export (with the fil ticket column and R TODO checkboxes) is committed as-is; fylr's CSV loader only reads the key column and xx-XX language columns.

Sealing

A sealed plugin is still a valid zip: the plugin folder with a plaintext manifest.yml, the whole plugin encrypted to fylr's public key beside it (fylr-sealed-plugin.enc, X25519 + XSalsa20-Poly1305 sealed box). Only a fylr holding the matching private key can open and run it.

fylr-build-plugin seal                     # builds the zip if needed, dev/CI key
fylr-build-plugin seal -pubkey <base64>    # production / marketplace-source key
fylr-build-plugin genkey                   # fresh keypair
fylr-build-plugin info my-plugin_sealed.zip

Sealing uses a public key only — no secrets in CI. With no -pubkey the dev/CI key is used: such a plugin opens only on a fylr built with -tags licensetest, which is what makes a public example (fylr-plugin-example-licensed) safe to publish. fylr opens sealed plugins via the pluginseal package — sealer and server share one source of truth and cannot drift:

plain, sealed, err := pluginseal.OpenPluginZip(artifact, keysThisBuildHolds...)

Release workflows

A release is cut by a manager on the GitHub release page; the workflow builds and publishes the artifact. Two templates live in templates/:

  • release-public.yaml — attach the zip to the release; fylr installs from releases/latest/download/<repo>.zip.
  • release-private.yaml — additionally publish to GitHub Pages under an unguessable per-repo UUID URL, since a private repo's release assets are not fetchable by fylr.

Either variant becomes a sealed release by switching make zip to make seal — no secrets needed.

readme

Writes a self-contained README: every relative image reference is inlined as a data: URI. This matters because most plugin repositories are private — once a README leaves the repo (into the plugin zip, then the marketplace) its relative asset paths are unreachable. build bundles it automatically as build/<name>/README.md.

build delivers it as build/<name>/README.md — next to manifest.yml, the one place fylr reads a plugin's docs: the marketplace reads it out of the release zip via HTTP range requests, and (since #80537) the plugin manager shows it as the installed plugin's README tab. No manifest key is involved; shipping the file is enough. The retired plugin.webfrontend.readme key is rejected by build — remove it from old manifests.

fylr-build-plugin readme [flags]
  --in               input markdown file (default "README.md")
  --out              output self-contained markdown file (default "build/README.md")
  --max-image-bytes  leave images larger than this many bytes as relative links (default 524288)

Documentation

Overview

Command fylr-build-plugin is the build driver for fylr plugins — the "make" that knows how a fylr plugin is put together. It is run from a plugin repo's root without a submodule or vendored include, e.g.

go run github.com/programmfabrik/fylr-build-plugin@latest build

It assembles build/<plugin.name>/ (loadable directly by fylr via plugin.paths), zips it for release, and can seal the zip for the fylr Plugin Marketplace (the former fylr-seal-plugin, merged here — the pluginseal package is imported by fylr to open sealed plugins).

The name follows the fylr convention: "fylr-plugin-*" is reserved for plugins, tooling is "fylr-<verb>-plugin".

Sealing (the former fylr-seal-plugin, merged here): a sealed plugin is still a valid zip that keeps the plugin folder with a plaintext manifest, the whole plugin encrypted to fylr's public key beside it. Sealing uses a PUBLIC key only, so it runs in any (public) build pipeline without a secret; the private key lives in fylr. fylr imports the pluginseal package to open sealed plugins — one source of truth, no drift.

Directories

Path Synopsis
Package pluginseal seals a fylr plugin zip into a "sealed plugin" — still a valid zip — and opens one back.
Package pluginseal seals a fylr plugin zip into a "sealed plugin" — still a valid zip — and opens one back.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL