OpenHealthSim

Create your first plugin

Run the fictional Acme example, scaffold a plugin and verify it against exact local SDK packages.

Try Acme#

Download author kit 1.0.0 and unzip the complete openhealthsim-author-kit-1.0.0 folder into a new location. Do not place it in a live lab data directory. Node.js 22 or 24 and npm are required.

From that extracted folder:

node setup.mjs
npm run verify
npm run typecheck
npm test

setup.mjs checks the included manifest before npm ci --ignore-scripts. It downloads only the pinned public third-party dependencies; the OpenHealthSim SDK packages come from sdk/*.tgz. Keep the lockfile and the entire SDK folder together. No public first-party npm release or private repository access is needed.

verify runs the fictional Acme mapping through the real public mapping/parameter/interface testkit. It checks exact message kinds, values, UCUM units, timestamps, unique repeat-reading IDs and malformed inputs. NIBP yields two new readings, HR is a display broadcast, and battery is a device event. There is no invented outbound vendor command.

typecheck checks the Acme plugin and generated practice-monitor scaffold. test runs their engineering/lifecycle cases. The Acme plugin test includes repeated configuration edits, replacements and no remaining registrations. These are public SDK contract tests; they do not prove hardware delivery or clinical suitability.

Read the worked example#

  • examples/acme/samples.ndjson contains the literal fictional datagrams.
  • examples/acme/mapping.json implements the data-only alternative.
  • examples/acme/plugin/server.js registers the codec/type through public services and the existing transport.
  • examples/acme/plugin/plugin.test.js and cases.mjs hold independent expectations.
  • examples/acme/README.md explains scope and a separately owned dev-host integration.

Make your plugin#

Create a new folder inside the extracted kit so it can resolve the parent project’s exact SDK installation:

node node_modules/create-i2l-sim-plugin/dist/bin.js my-monitor --kind interface
cd my-monitor
npm run typecheck
npm test

Do not run a separate npm install in the new folder while its SDK dependencies still name unpublished registry versions. The parent kit already supplies them. If you move the project elsewhere, bind those dependencies and overrides to the exact local SDK tarballs first.

Available kinds are interface, output, screen, score, importer and hook. The scaffold’s greeting/example is a starting point. Keep its manifest, Config, tests, minimal contract host and OS/Node workflow while implementing your actual feature. The included CI workflow is a template, not evidence that all six jobs have run.

Implement through public contracts#

Declare the services your plugin injects and access them from its context. Register a codec/type rather than opening a hidden second socket. Keep listener cleanup, subscriptions and pending work inside the contributor lifecycle. After an awaited lookup, verify that the selected owner is still current before publishing its result.

Put clinical values, thresholds and device assumptions in reviewed configuration. A new scoring table needs clinical review independently of passing engineering tests. Use only documented browser slots: for example, screen.layouts is a paired output layout and console.pages is a console page; there is no generic public console.panels slot.

Add literal feature tests, malformed inputs, legitimate repeat readings and unload/replacement during an awaited operation. Preserve the existing tests; a test that only repeats your implementation is weak evidence. Use real loopback/browser/provider integration only when the feature relies on that boundary.

Inspect the actual artifact#

From your plugin folder, run the included skill inspector using the appropriate relative path:

node ../skills/i2l-sim-plugin/scripts/inspect-package.mjs .
npm pack --dry-run
npm pack

Read permissions and archive entries. Include the real server/client files and assets, compatible engine range, licence and third-party notices. Exclude keys, recordings, lab profiles, developer caches and real patient/learner data. npm pack prepares an artifact; it does not install, approve, publish or activate it.

The Acme production package intentionally includes only its server and README. Its test harness stays in the author project. Preserve third-party licence/terminology notices when redistributing code or data.

Install on a separate dev host#

The author kit is not the full host application. Obtain a host build separately. Start an owned development profile/data directory and use the application’s normal plugin add, permission and configuration flow. Keep the same explicit dev/profile flags on subsequent commands. Do not add the kit’s entire SDK dependency tree to the running plugin directory.

Check the actual feature, edit/reload it, then remove the owned dev plugin and verify cleanup. Data purging is destructive; use it only for your disposable fixture. A lab installation or Store enable needs its own human approval. Read the public contracts and the administrator install guide.