Plugin Packaging

Gestalt uses one package format for:

• provider plugins
• web UI bundles

Each package is described by a manifest file named one of:

• plugin.yaml
• plugin.yml
• plugin.json

How Plugins Enter A Config

There are three ways to point at a packaged plugin from config.yaml.

command

Use a local executable directly.

integrations:
  example:
    plugin:
      command: ./bin/example-provider
      config:
        greeting: hello

This is best for local development.

package

Load a local directory, local archive, or HTTPS archive.

integrations:
  example:
    plugin:
      package: ./dist/example-provider.tar.gz

source

Resolve a versioned plugin source during init.

In config, that looks like source: github.com/acme/plugins/example plus version: 1.2.3.

This is the cleanest path for reusable, versioned packages.

What init Does For Packaged Plugins

gestaltd init resolves and prepares:

• plugin.package
• plugin.source
• ui.plugin.package
• ui.plugin.source

It writes lock state and extracts the prepared artifacts under .gestalt/.

Packaging Commands

Package A Plugin Directory

gestaltd plugin package --input ./my-plugin --output ./dist/my-plugin.tar.gz

Build A Cross-Platform Release

gestaltd plugin release --version 0.1.0

Run plugin release from the plugin source directory. It compiles the plugin, produces release archives, and writes a checksums file.

Declarative-Only Packages

A provider manifest can be declarative-only. In that case the package contains a manifest and optional schemas or assets, but no executable artifact is required.

That is useful when you want to ship:

• a reusable declarative REST provider
• a reusable OpenAPI-backed integration
• a reusable web UI bundle

Executable Packages

Executable provider packages add artifacts plus entrypoints.provider.artifact_path to the manifest. gestaltd plugin release builds that structure for you.

Package Layout

Typical contents:

• plugin.yaml
• artifacts/... for compiled binaries
• schemas/config.schema.json or schemas/config.schema.yaml for provider config validation
• assets/... for icons or web assets

The exact layout is controlled by the manifest.