Crate hm_plugin_sdk 

Authoring SDK for hm plugins.

Plugins build to cdylib and target wasm32-wasip1. The canonical plugin entry point is the register_plugin! macro, which wires every capability the plugin implements to the right Extism export.

use hm_plugin_sdk::*;
use hm_plugin_protocol::*;

struct MyExec;
impl StepExecutor for MyExec {
    fn run(&self, input: ExecutorInput) -> Result<StepResult, PluginError> {
        host::log(Level::Info, &format!("running {}", input.step.key));
        Ok(StepResult { exit_code: 0, committed_snapshot: None, artifacts: vec![] })
    }
}

register_plugin!(
    manifest = PluginManifest {
        api_version: HM_PLUGIN_API_VERSION,
        name: "my-exec".into(),
        version: semver::Version::parse("0.1.0").unwrap(),
        description: "demo".into(),
        capabilities: vec![Capability::StepExecutor(StepExecutorSpec {
            runner: "demo".into(), default: false, step_schema: None,
        })],
        required_host_fns: vec!["hm_log".into()],
        config_schema: None,
        allowed_hosts: vec![],
    },
    executor = MyExec,
);

Re-exports

pub use executor::StepExecutor;

pub use hook::LifecycleHook;

pub use output::OutputFormatter;

pub use subcommand::SubcommandPlugin;

pub use extism_pdk;

Modules

error

Error and exit-info types returned by plugin capability exports.

events

Build-time events. Produced by the orchestrator (host) and fanned out to output formatters, lifecycle hooks, and (via the host re-broadcast of hm_emit_step_log) any subscriber.

executor

hook

host

Safe wrappers around the host functions imported via Extism’s host_fn! block. Plugin code calls these instead of touching extism-pdk directly.

host_abi

Wire types used as host-function arguments and return values. Plugins import these to talk to the hm host fns; the host imports them to expose those fns.

ir

Pipeline IR, the v0 wire format consumed by the hm binary.

manifest

Build helpers for plugin manifests. Today this file is a re-export shim; future expansion will add a manifest! {} declarative macro.

output

subcommand

Macros

register_plugin

Generate hm_manifest + capability exports for a plugin.

Structs

ArchiveId

Opaque archive handle. The plugin streams bytes via hm_archive_read(id, offset, max).

ArchiveReadArgs

Host-fn argument struct for the corresponding hm_archive_read host function.

ArtifactRef

Cache

CallbackData

Host-fn argument struct for the corresponding hm_loopback_recv host function.

CommandStep

DockerCommitArgs

Host-fn argument struct for hm_docker_commit.

DockerExecArgs

Host-fn argument struct for hm_docker_exec.

DockerExtractArgs

Host-fn argument struct for hm_docker_extract_workspace.

DockerStartArgs

Host-fn argument struct for hm_docker_start_container.

ExecutorInput

ExitInfo

Returned by a subcommand plugin from hm_subcommand_run. The host translates exit_code into the process exit code.

HookEvent

Hook entry-point input. The host wraps a BuildEvent and tells the plugin which phase this call is.

KeyringArgs

Host-fn argument struct for the corresponding hm_keyring_get / hm_keyring_delete host function.

KeyringSetArgs

Host-fn argument struct for the corresponding hm_keyring_set host function.

LifecycleHookSpec

LoopbackHandle

Opaque handle returned by hm_spawn_loopback. Bound to the plugin instance.

LoopbackRecvArgs

Host-fn argument struct for the corresponding hm_loopback_recv host function.

OutputFormatterSpec

Pipeline

PlanSummary

Compact summary of the resolved IR included in BuildStart. Lets output formatters print a header without needing the full pipeline.

PluginError

Error returned from any capability export. The host renders these with the code field; downstream tooling matches on it.

PluginManifest

Returned by an Extism plugin’s hm_manifest() export.

SnapshotRef

Opaque snapshot reference. For the docker plugin this is an image tag; other plugins are free to encode their own format. The host never inspects the contents.

SocketHandle

Opaque socket handle returned by hm_unix_socket_connect. Bound to the plugin instance that opened it.

SocketReadArgs

Host-fn argument struct for the corresponding hm_socket_read host function.

SocketWriteArgs

Host-fn argument struct for the corresponding hm_socket_write host function.

StepExecutorSpec

StepResult

SubcommandInput

Carried into the plugin’s subcommand entry point. The host has already parsed argv on the plugin’s behalf using the schema the plugin declared in its manifest.

SubcommandSpec

TtyConfirmArgs

Host-fn argument struct for the corresponding hm_tty_confirm host function.

TtyPromptArgs

Host-fn argument struct for the corresponding hm_tty_prompt host function.

WaitStep

Enums

BuildEvent

CacheDecision

Host-decided cache outcome. The executor honours this; it does not re-decide.

Capability

HookEventKind

Subset of crate::hook::HookEvent discriminants used at manifest time.

HookOutcome

HookPhase

KvScope

Level

StdStream

Step

Constants

HM_PLUGIN_API_VERSION

Wire-format version. Plugins whose manifest reports a different version are rejected at load time. Bump when adding any new required field to any wire-level struct.

Type Aliases

ClapJson

Clap-derived JSON describing a subcommand’s argument schema. Produced by the SDK helper [crate::manifest::clap_json_from] (added in [hm-plugin-sdk]).

JsonSchema

JSON Schema fragment (serde-passthrough). Used to validate plugin-specific config blobs and runner_args.