:::note Generated reference Generated from honeyframeapi 0.1.8 — do not edit by hand. :::

honeyframeapi.plugin_dev

plugin_dev.py — a local developer kit for Honeyframe kernel plugins.

Scaffold, validate, run, and pack a plugin directory (plugin.json + entry .py files) with zero platform install and zero monorepo checkout. The rules here mirror the platform kernel (validate_descriptor in services/plugins/kernel.py) and the child protocol (services/plugins/ harness.py) so a developer gets the same feedback locally that install gives — but the platform kernel is AUTHORITATIVE: its validator runs again at install, and it runs plugins in an isolated, credential-scrubbed subprocess. Local run here is NOT sandboxed — it exec()s the entry file in this process, on this machine, with your own privileges.

Stdlib only. Docs: https://docs.honeyframe.io/

class PluginDevError

Bases: Exception

A local plugin-kit failure (invalid descriptor, missing entry, …).

Functions

validate_descriptor()

validate_descriptor(data: Any, *, root: str | None = None) -> tuple[dict | None, list[str]]

Validate a parsed plugin.json exactly as the platform kernel does.

Returns (normalized_descriptor, errors). When root is given, each executed component's entry must exist as a regular file inside it. Never raises — malformed input comes back as honest error strings.

load_and_validate()

load_and_validate(plugin_dir: str) -> tuple[dict | None, list[str]]

Read <plugin_dir>/plugin.json and validate it with entry-file checks.

run_component()

run_component(plugin_dir: str, component_name: str, *, op: str | None = None, params: dict | None = None, input_csv: str | None = None, source: str | None = None, output: str | None = None, pass_env: bool = True) -> tuple[dict, str | None]

Run one component locally. Returns (summary, output_path_or_None).

summary is the same JSON the platform shim emits for the op. Raises PluginDevError for kit-level problems and re-raises the shim's own TypeError/ValueError (or the entry's own exception) unchanged, so the message matches what install/run would report.

The entry file runs IN THIS PROCESS as the current user — not sandboxed. pass_env=False hides every HONEYFRAME_* / HUB_* environment variable (tokens, passwords) from it for the duration of the run; the honeyframe plugin run CLI does that unless --pass-env is given.

init_plugin()

init_plugin(target_dir: str, ctype: str, plugin_id: str | None = None) -> tuple[str, list[str]]

Scaffold a plugin dir. Returns (plugin_id, [written relpaths]). The result always passes validate_descriptor.

pack_plugin()

pack_plugin(plugin_dir: str, out: str | None = None) -> str

Validate then zip the plugin (plugin.json at the archive root). Excludes dotfiles, __pycache__, *.pyc, existing zips and symlinks (symlinked directories are not descended either). Refuses to pack an invalid plugin — returns the archive path on success.

summarize_descriptor()

summarize_descriptor(desc: dict) -> str

Constants

Name	Value
DESCRIPTOR_FILENAME	'plugin.json'
SUPPORTED_COMPONENT_TYPES	('recipe', 'transform', 'connector', 'scenario_step')
DATA_COMPONENT_TYPES	('monitor_adapter',)
PARAM_TYPES	frozenset({'string', 'textarea', 'int', 'float', 'bool', 'select', 'column', 'columns', 'connector'})
SCRUBBED_ENV_PREFIXES	('HONEYFRAME_', 'HUB_')

---

Verified against honeyframeapi 0.1.8.