Build your first extension

This journey starts from a minimal, valid `Extension` resource, then adds capabilities one by one. The scaffold requests no permission and exposes no external effect by default.

Prerequisites

The developer tooling in this version runs from an Ormuz repository checkout with Node 22. It uses the same contract validator as the platform; it is not yet a standalone partner npm SDK.

Create the scaffold

Shell

cd cli
node src/index.js extension init acme_pay --kind provider_integration

The command creates extension.yaml, the generated runtime projections, and a minimal API entry point. extension.yaml is the canonical editable source of the package. Generated files must not be edited directly.

Shell

node src/index.js extension check ../plugins/acme_pay

The scaffold must already pass this validation. Readiness warnings are expected while you have not yet added capabilities. See Validate an extension.

Understand `extension.yaml`

The scaffold produces a declarative resource in this form:

YAML

apiVersion: ormuz.io/v1alpha1
kind: Extension
metadata:
name: acme_pay
title: Acme Pay
spec:
version: 0.1.0
platformApiVersion: "1"
defaultLocale: en-US
supportedLocales:
  - en-US
  - fr-FR
runtime:
  api: ./api/index.cjs
extensionKind: provider_integration
cardinality: multi
capabilities: []
integrationMechanisms: []
activation:
  when: on_install
channels: []
contributes:
  nodes: []
  tools: []

metadata.name is the extension's stable identity. It uses lowercase snake_case, is unique on the platform, and becomes the namespace for its contributions. The ormuz namespace is reserved for Core executables.

The manifest declares serializable facts: identity, available runtimes, extension type, channels, and contributions. Execution functions and credentials are never serialized in it.

Generated projections

Ormuz projects extension.yaml into the representations required by the runtimes. They are generated so that every surface consumes the same declarative contract.

Text

extension.yaml                   # editable source
├── manifest.cjs                 # generated
├── manifest.mjs                 # generated
└── api/extension.descriptor.cjs # generated

After changing the manifest, run extension generate when necessary. The preflight reports a projection that has become stale.

Shell

node src/index.js extension generate ../plugins/acme_pay
node src/index.js extension check ../plugins/acme_pay

Some runtime contracts deliberately remain code, including configSchema, event payload contracts, and behaviors. They complement the manifest without creating a second editable source for its structural facts.