fylr-build-plugin

command module
v1.8.0 Latest Latest
Warning

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

Go to latest
Published: Aug 6, 2026 License: Unlicense Imports: 19 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 + concatenated into plugin.webfrontend.url
│   ├── lib/*.js          vendored JS, appended to that same bundle verbatim
│   ├── *.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.

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.
  • webfrontend.coffee1 files compile (CoffeeScript 1.x — the version the plugins are stuck on, hence the key — with -b) and concatenate — in list order — into plugin.webfrontend.url under base_url_prefix. webfrontend.js files join that same bundle verbatim, after the compiled CoffeeScript and in list order: fylr loads only the one bundle named by plugin.webfrontend.url, 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.
  • 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:
  install:               # server-side delivery, copied verbatim
    - server
    - fas_config
    - l10n
  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:
  coffee1:               # CoffeeScript 1.x (the version plugins are stuck
    - webfrontend/MyClass.coffee        # on), compiled + concatenated in this
    - webfrontend/UsesMyClass.coffee    # order into plugin.webfrontend.url
  js:                    # plain JS (a vendored library): appended to that
    - webfrontend/lib/vendor.js         # same bundle verbatim, in this order
  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>"
Bundles

webfrontend.coffee1/js is shorthand for the one bundle nearly every plugin has: the file named by plugin.webfrontend.url. A plugin that assembles a second file declares it explicitly:

build:
  bundles:
    - out: updater/DANTEUpdater.js       # anywhere in the plugin folder
      sources:
        - src/updater/DANTEUpdater.js    # .js     -> verbatim
        - webfrontend/DANTEUtil.coffee   # .coffee -> compiled

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 shorthand always puts CoffeeScript before JS, but the custom-data-type updaters need a hand-written Node script first with the shared utility appended, and a plugin vendoring a library may need it either side of 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.

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:

release:
  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