Publish

From a plugin's folder to the Install button of every Hodi: test, try on a test Hodi, build the file, then have it checked and signed through the plugin registry.

In short

A plugin goes through four stages before it reaches people. The first three are done alone, on one's own machine. The last one goes through Hodi's maintainer.

The plugin template already has everything: the SDK, the scripts and the CI. There is nothing more to install.

Test

What a test does

A test runs the plugin's server part the way Hodi runs it:

1. The SDK builds the plugin.
2. It loads it in the same sandbox as Hodi.
3. It calls its routes with the same checks as Hodi.

Around it is a small Hodi in memory: a household, its admin, and stand-ins for sites, e-mails, notifications and the AI. So a test never sends anything to anyone. It runs the same way on one's machine and in the CI.

An example

The plugin template already has this file. It asks for the POST /hello route and looks at the answer:

import assert from 'node:assert/strict'
import { after, describe, it } from 'node:test'
import { testPlugin } from '@hodi-app/plugin-sdk/testing'

describe('my-plugin', async () => {
  const hodi = await testPlugin('.', {
    settings: {
      greeting: 'Hi'
    }
  })
  after(() => hodi.stop())

  it('answers a child too', async () => {
    const child = await hodi.addPerson({
      name: 'Zoe',
      kind: 'child'
    })
    const answer = await hodi.route('POST /hello', {
      as: child
    })
    assert.equal(answer.status, 200)
  })
})

To run the tests:

npm test

The template's CI runs them again at every push. A plugin that passes its tests behaves the same once installed in a real Hodi.

testPlugin's options

testPlugin('.') takes the plugin's folder. The second argument, optional, prepares the small Hodi:

What the small Hodi offers

Try on a test Hodi

A test checks the server part. To see the web part too, a real Hodi is needed: Developer mode installs the plugin on it, then updates it at every save.

What is needed

• A Hodi of one's own, on one's machine for example (http://localhost:3000).
• Being its server's admin.

A test Hodi keeps the trials apart from one's household's data.

The steps

1. Open Server › Plugins on the test Hodi.
2. Turn on Developer mode: Hodi shows a code, only once.
3. Copy this code.
4. In the plugin's folder, run the command below, replacing THE_CODE.
5. Leave the command running while working.

npx hodi-plugin dev --server http://localhost:3000 --code THE_CODE

What happens next

At every save of a file, the command:

1. builds the plugin again;
2. sends it to the test Hodi;
3. waits for Hodi to restart with the new version (a few seconds);
4. shows the plugin's log in the terminal.

In Hodi, the plugin wears the In development badge. Its pages show even unsigned, and it keeps its data from one version to the next. Ctrl+C stops the command.

Build

The plugin's file

npm run build

The command writes a single file, dist/<id>-<version>.hodi-plugin. For example dist/hello-world-0.1.0.hodi-plugin. This is the file people install.

Installing it by hand

Any admin can install this file, even on a server they only manage from their browser:

1. Open Server › Plugins.
2. Click Add a plugin and choose the file.
3. Read what Hodi shows: the name, the version and the permissions.
4. Confirm the install.

What the admin sees before installing

Hodi looks at whether the file is signed, and tells the admin:

The permissions kept for signed plugins are listed in The manifest.

Getting verified

Why a signature

A signature tells Hodi who made a plugin. Hodi trusts only one key: its maintainer's.

A plugin's pages run in Hodi's page, with the session of the person signed in. That is why only a signed plugin, or the one in development, can show its pages.

The steps

1. Put the plugin in a public GitHub repository.
2. Publish a release v<version> (for example v0.1.0) with its .hodi-plugin file.
3. Add the plugin to the plugin registry with a pull request.
4. The maintainer reads the plugin's code.
5. If it follows Hodi's rules, they sign this version and accept the pull request.

In the plugin template, pushing a v0.1.0 tag is enough for step 2: the CI builds the file and creates the release on its own.

The registry entry

The registry is a plain list, the plugins.json file. An entry needs two fields, and the registry's npm run index command fills the rest from the release:

{
  "repo": "https://github.com/me/hodi-plugin-hello-world",
  "version": "0.1.0"
}

The registry's README details the commands to run before the pull request.

Then

• The plugin shows in Server › Plugins › Available of every Hodi.
• It installs from there in one click.
• Each new version goes through a new pull request.

That new version is read, then signed in turn.

Hodi's rules

The maintainer checks each of these rules before signing a plugin.