38 lines
1.8 KiB
Markdown
38 lines
1.8 KiB
Markdown
# Hello-World example plugin
|
|
|
|
Minimum-viable plugin demonstrating the `@toolctrl/plugin-sdk` shape.
|
|
|
|
## Files
|
|
|
|
- `plugin.toml` — the manifest the host parses + verifies. The `wasmSha256`, `signature`, and `signedBy` fields are placeholders; the operator overwrites them after signing the compiled `.wasm` against a trusted Ed25519 keypair.
|
|
- `handler.ts` — the plugin source. Exports `handleHello`, the hook the manifest references via `[[hooks]] export = "handleHello"`.
|
|
|
|
## Build
|
|
|
|
The plugin build CLI is **deferred** to Phase 06 Task #23 (see `docs/improvement-plan/06-plugin-system/wasm-sandbox.md`). Until then, plugin authors compile to WASM with their preferred toolchain. Two practical paths today:
|
|
|
|
1. **AssemblyScript** — write the handler in AssemblyScript syntax and run `asc handler.ts -o plugin.wasm --optimize`.
|
|
2. **Rust** — port the handler to a `#[no_mangle]` extern function and build with `wasm-pack build --target nodejs`.
|
|
|
|
Both produce a `.wasm` binary the runtime can instantiate.
|
|
|
|
## Sign + install
|
|
|
|
Once the binary is built:
|
|
|
|
```bash
|
|
# Compute the hash and update the manifest in-place.
|
|
sha256sum plugin.wasm
|
|
|
|
# Sign the .wasm with the publisher's Ed25519 private key.
|
|
# (Sign helper for foundation: use Node's crypto.sign with no algorithm.)
|
|
node -e "const c=require('crypto'); const fs=require('fs'); \
|
|
const key=c.createPrivateKey({key: fs.readFileSync('publisher.priv'), format:'pem'}); \
|
|
process.stdout.write(c.sign(null, fs.readFileSync('plugin.wasm'), key).toString('hex'))"
|
|
|
|
# Drop the signed binary + manifest into the host's plugin volume.
|
|
cp plugin.wasm plugin.toml <plugin-volume>/<plugin-id>/1.0.0/
|
|
```
|
|
|
|
The operator then ensures the Ed25519 public key matching the signature is in `PLUGIN_TRUSTED_PUBLIC_KEYS` and inserts a row into the `Plugin` table.
|