Add-ons

An add-on, in the design's own words, is "a module we do not bundle": code that plugs into rafa without being part of the published package. rafa's issue tracker, its sync strategies and its outputs sit behind small interfaces, so that another one can be added this way instead of by changing rafa. This page describes where add-ons sit in rafa's target layout (Repository layout), then what loads today.

Where add-ons live

In the target layout, add-ons live in a folder addons/ beside packages/ in rafa's repository (#1257). Each add-on is a workspace package that publishes on its own, under @open-tomato/rafa-<name>, declares the rafa versions it works with, and is never pulled into the command-line bundle. What it means at each step:

• A project using rafa: nothing changes.
• rafa's repository: an add-on is built, tested and released there, beside the command line, at its own pace.
• An add-on's user, before npm installs exist: a path source to a checkout, as in the last section.

Two companion specs make add-ons useful during a run. An add-on can listen to a run's events, such as a halt, a blocked task or a pull request, beside the terminal output (#1258). An add-on that needs a running service says so once, and every loop checks it before its first session, with the rest of the preflight (#1260).

The first three add-ons

Each connects one of Open Tomato's sibling projects to rafa. The projects stay in their own repositories; the add-on is the bridge.

Add-on	Connects	Lightest use	Heavier use	Spec
rafa-notifications	ned, which delivers messages to chats, files or a phone	one person: a phone rings when a loop halts or needs a decision	a team: alerts to a shared chat, notices to a file journal	#1259
rafa-sandbox	Grow Box, sandbox machines	one person: a database in a container on the laptop	a team: visual checks in a large sandbox each project builds once; a shared runner where every project uses the machine's one box	#1261
rafa-d2c	design-to-code, from a design export to components	one person: imports a design export and seeds components, on request	a project building UI with loops: every UI task names its reference and its visual checks	#1262

[TBD: install and config steps for each add-on, once its spec is built]

What loads in 0.47.0

A project names each module under modules: and trusts it by name under allowList:. At 0.47.0, rafa loads modules from a folder only, a path source:

# .rafa/config.yaml
modules:
  - path: addons/rafa-notifications
allowList:
  - "@open-tomato/rafa-notifications"

The folder's package.json carries a rafa key, the module's manifest, which says what the module provides. rafa module list shows each configured module and what became of it. The rafa-notifications add-on above does not exist yet, so today the same config reports a missing folder:

rafa module list

warn: allowList names the module "@open-tomato/rafa-notifications", which no modules: source gives
Modules:
  modules[0] (no version): disabled, disabled; types no types read; from path addons/rafa-notifications
    problem: <project>/addons/rafa-notifications/package.json cannot be read as JSON: ENOENT: no such file or directory, …

A module that exists loads the same way. The service sync module in rafa's repository, named by a path source to a clone of that repository, lists as loaded, enabled with its adapter, sync/service (Connect devices has the block).

A source of kind npm or github is refused at 0.47.0, with a warning that names why:

npm source "@open-tomato/rafa-sync-service" is refused: phase 1 loads path sources alone, and installing a package or a repository is phase 7's

So for now a path source is for rafa's own repository and for development: it points at a folder on your machine, such as a checkout of rafa. Installing add-ons from npm is a later phase of the add-ons spec (#29).

Decisions not taken

Notification code inside rafa itself was rejected in favour of an add-on that sends through ned (#1259). Services in rafa's core, a sandbox: section in rafa's own config, and one sandbox for every project were rejected for rafa-sandbox (#1261). The reasons are in each spec's design.