@elftia/plugin-kit

Producer-side verification and deterministic release packaging for Elftia plugins.

elftia-plugin stamp dist/my-plugin
elftia-plugin verify dist/my-plugin
elftia-plugin pack dist/my-plugin --out release/1.0.0
elftia-plugin release dist/my-plugin --out release

dist/<id>/ must be the complete install tree with elftia-plugin.json at its root. The public CLI rejects symlinks, junctions, special files, unsafe plugin ids, and any node_modules path segment outside a declared prebuilds target. It also rejects developer-only state and metadata at any depth, including .computer-use/, .github/, .git/, IDE settings, caches, logs, temporary files, and editor lock files. Runtime metadata such as .claude-plugin/plugin.json remains valid.

Run stamp only after every code bundle has reached its final bytes. It writes one canonical sha512-<base64> checksum for every declared code entry. The producer must author the execution ABI; the tool never guesses or repairs it:

| Contribution | Resolved below | Required execution | | ------------ | -------------- | --------------------- | | main | main/ | none | | renderer | renderer/ | opaque-frame-v1 | | pet | renderer/ | opaque-frame-v1 | | quickChat | renderer/ | dedicated-window-v1 |

verify, pack, and release are read-only with respect to the plugin tree. They reject missing, escaping, linked, non-file, unpinned, or byte-mismatched entries instead of silently restamping them. A producer should therefore run its bundle steps, then stamp, then verify or package operations.

Native dependencies use the only supported native channel:

{
  "supportedPlatforms": ["win32-x64", "darwin-x64", "linux-x64"]
}

The declaration must exactly match the non-empty directories under prebuilds/. Target names use Node's native process.platform-process.arch spelling. Each target directory may contain the addon, companion dynamic libraries, wasm, data, and other runtime files. No asarUnpack declaration is needed because installed plugin trees live outside app.asar.

pack produces <id>.epkg plus an external same-stem <id>.json sidecar. An EPKG is a standard ZIP container whose root contains elftia-plugin.json. The sidecar stays outside the EPKG because its SHA-256 covers the complete container bytes. EPKG v2 keeps those standard ZIP bytes and records formatVersion: 2 in the sidecar. release derives the version subdirectory from the manifest. The writer uses the host's strict ZIP32 subset: stored/deflated entries only, with no encryption, data descriptors, or ZIP64. It emits portable Unix regular file attributes on every OS and limits modes to 0644 or 0755; execute bits, shebang scripts, and recognized executable binaries retain executable semantics. The host rejects path aliases, special-file attributes, local/central metadata disagreement, CRC failures, and DEFLATE output that exceeds its declared size.

The legacy Elftia repository script scripts/pack-plugin-package.mjs is a compatibility wrapper over this package and applies the same fail-closed tree policy. New producers should use the public CLI directly.

fixtures/native-prebuilds/ is a minimal dependency-free N-API producer. Its CI matrix builds and loads the addon on Windows, macOS, and Linux, then merges the three outputs into one multi-platform transport package.