Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,37 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,23 @@
|
||||
/**
|
||||
* Hello-World example plugin source.
|
||||
*
|
||||
* Plugin authors write TypeScript / AssemblyScript / Rust against the
|
||||
* `@toolctrl/plugin-sdk` types, then compile to a single `.wasm` binary
|
||||
* with their toolchain of choice (wasm-pack, AssemblyScript's `asc`,
|
||||
* etc.). The host runtime treats the .wasm as opaque — only its
|
||||
* exports (`handleHello` here) and the `plugin.toml` manifest matter.
|
||||
*
|
||||
* Building this file to WASM is intentionally outside the scope of
|
||||
* the foundation: the `toolctrl plugin build` CLI is deferred (see
|
||||
* `docs/improvement-plan/06-plugin-system/wasm-sandbox.md` Deviations).
|
||||
* Operators wanting a working hello-world today can hand-compile via
|
||||
* AssemblyScript or use any other WASM toolchain that produces a flat
|
||||
* function export — the runtime contract is just `(arg) -> result`.
|
||||
*/
|
||||
|
||||
import { defineHook } from "../../src/index.js";
|
||||
|
||||
export const handleHello = defineHook<{ name: string }, { greeting: string }>((input, ctx) => {
|
||||
ctx.log.info({ name: input.name }, "hello-plugin.invoked");
|
||||
return { greeting: `Hello, ${input.name}!` };
|
||||
});
|
||||
@@ -0,0 +1,28 @@
|
||||
# Phase 06 #21 — Hello-World example plugin manifest.
|
||||
#
|
||||
# A plugin author ships exactly this file alongside the .wasm binary.
|
||||
# The runtime parses it via @toolctrl/plugin-runtime's PluginManifestSchema
|
||||
# (note: foundation supports both TOML and JSON shape — the schema works
|
||||
# off the parsed object so authors may choose the format their toolchain
|
||||
# emits). The values below are illustrative; the wasmSha256 / signature /
|
||||
# signedBy fields are placeholders that an operator replaces after
|
||||
# signing the actual binary with `toolctrl plugin sign` (deferred CLI,
|
||||
# see Deviations in wasm-sandbox.md).
|
||||
|
||||
schemaVersion = 1
|
||||
id = "de.toolctrl.hello"
|
||||
version = "1.0.0"
|
||||
name = "Hello World"
|
||||
description = "Returns a greeting. Demonstrates the minimum viable plugin."
|
||||
entry = "plugin.wasm"
|
||||
wasmSha256 = "0000000000000000000000000000000000000000000000000000000000000000"
|
||||
signature = "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
|
||||
signedBy = "0000000000000000000000000000000000000000000000000000000000000000"
|
||||
allowedHosts = []
|
||||
|
||||
[[capabilities]]
|
||||
name = "log"
|
||||
|
||||
[[hooks]]
|
||||
name = "onHello"
|
||||
export = "handleHello"
|
||||
Reference in new issue
Block a user