Construire votre première extension

Ce parcours part d’un resource Extension minimal et valide, puis ajoute les capacités une par une. Le squelette ne demande aucune permission et n’expose aucun effet externe par défaut.

Prérequis

Le tooling développeur de cette version s’exécute depuis un checkout du repository Ormuz avec Node 22. Il s’appuie sur le même validateur de contrat que la plateforme ; il ne constitue pas encore un SDK npm partenaire autonome.

Créer le squelette

Shell

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

La commande crée extension.yaml, les projections runtime générées et un entrypoint API minimal. extension.yaml est la source éditable canonique du package. Les fichiers générés ne doivent pas être modifiés directement.

Shell

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

Le squelette doit déjà passer cette validation. Les avertissements de readiness sont attendus tant que vous n’avez pas encore ajouté de capacités. Voir Valider une extension.

Comprendre `extension.yaml`

Le scaffold produit un resource déclaratif de cette forme :

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 est l’identité stable de l’extension. Elle utilise le lowercase snake_case, est unique dans la plateforme et devient le namespace de ses contributions. Le namespace ormuz est réservé aux exécutables Core.

Le manifeste déclare des faits sérialisables : identité, runtimes disponibles, type d’extension, channels et contributions. Les fonctions d’exécution et les credentials n’y sont jamais sérialisés.

Projections générées

Ormuz projette extension.yaml vers les représentations nécessaires aux runtimes. Elles sont générées afin que toutes les surfaces consomment le même contrat déclaratif.

Text

extension.yaml                   # source éditable
├── manifest.cjs                 # généré
├── manifest.mjs                 # généré
└── api/extension.descriptor.cjs # généré

Après une modification du manifeste, exécutez extension generate si nécessaire. Le preflight signale une projection devenue obsolète.

Shell

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

Certains contrats runtime restent volontairement du code, notamment configSchema, les event payload contracts et les comportements. Ils complètent le manifeste sans créer une seconde source éditable pour ses faits structurels.