Improve external plugin developer experience

[intel352]

Summary

After integrating workflow-plugin-authz v0.3.0 into a production project, several friction points in the external plugin experience became apparent. This issue collects recommendations for streamlining the plugin lifecycle.

1. Standardize tarball structure across releases

The tarball contents changed between v0.2.0 and v0.3.0:

• v0.2.0: workflow-plugin-authz-darwin-arm64 (platform-suffixed binary, no plugin.json)
• v0.3.0: workflow-plugin-authz (bare binary) + plugin.json

Consumers need conditional logic to handle both:

# Must handle both old and new tarball layouts
if [ -f "${DEST}/${NAME}-${OS}-${ARCH}" ]; then
  mv "${DEST}/${NAME}-${OS}-${ARCH}" "${DEST}/${NAME}"
fi

Recommendation: Document and enforce a standard tarball layout going forward. The v0.3.0 format (bare binary + plugin.json) is the right one — just ensure goreleaser configs across all plugins produce it consistently.

2. Add wfctl plugin install command

Currently, installing a plugin requires:

1. Determine OS/arch
2. Construct the GitHub release URL
3. Download and extract the tarball
4. Handle platform-suffix renaming
5. Ensure plugin.json is present
6. Place in the correct directory structure (plugins/<name>/<name>)

This is boilerplate that every consumer reimplements. A built-in command would eliminate it:

# Install from GitHub release
wfctl plugin install GoCodeAlone/workflow-plugin-authz@v0.3.0

# Install to custom dir
wfctl plugin install --dir ./plugins GoCodeAlone/workflow-plugin-authz@v0.3.0

# List installed plugins
wfctl plugin list --dir ./plugins

# Upgrade
wfctl plugin upgrade --dir ./plugins GoCodeAlone/workflow-plugin-authz

This could read from the plugin registry (wfctl registry_search already exists) to resolve names to GitHub repos.

3. Plugin version pinning and lockfile

There's no way to declaratively pin plugin versions. Consumers must hardcode versions in scripts and Dockerfiles. A plugins.lock or wfctl.yaml file would allow:

# wfctl.yaml or plugins.lock
plugins:
  workflow-plugin-authz:
    version: v0.3.0
    repository: GoCodeAlone/workflow-plugin-authz

Then wfctl plugin install (with no args) installs everything from the lockfile, similar to npm install reading package-lock.json.

4. Plugin manifest should include version from release tag

Currently plugin.json has "version": "1.0.0" even in the v0.3.0 release (see #authz-version-mismatch). The manifest version should match the release tag so consumers and tooling can verify they have the correct binary. goreleaser could template this automatically.

5. Validate plugin compatibility at load time

The manifest includes minEngineVersion but it's unclear whether the engine checks this at load time. If it doesn't, it should — loading a plugin built against a newer engine version can cause subtle runtime failures.

Priority

Items 1-2 would have the highest impact on developer experience. Item 3 is a nice-to-have for reproducible builds. Items 4-5 are correctness improvements.