also looking at this
docs: make plugin authoring a first-class, accurate workflow
#51
2 files
+72
-0
Review threads live on the whole diff, not on one commit, so none are shown here - a thread's line means something in the branch's final form, and painting it into an intermediate step would put it on code it is not about.
| @@ -2,6 +2,61 @@ | ||
| 2 | 2 | |
| 3 | 3 | This guide explains how to develop plugins for Den Shell. Plugins can extend the shell with custom commands, hooks, and completion providers. |
| 4 | 4 | |
| 5 | ## Plugin types & current status | |
| 6 | ||
| 7 | Den has three ways to extend the shell, at different maturity levels. This table | |
| 8 | is the source of truth; the rest of this guide covers each in detail. | |
| 9 | ||
| 10 | | Type | What it is | Status | Start here | | |
| 11 | | --- | --- | --- | --- | | |
| 12 | | **WebAssembly plugins** | A separately-compiled `.wasm` module Den runs via the `wasm` builtin | ✅ **Works today** in a stock build | [`examples/plugins/wasm/`](../examples/plugins/wasm/) | | |
| 13 | | **Native (compiled-in) plugins** | Zig plugins registered through the hook/command/completion API and compiled into the binary | ✅ Works for plugins built into Den | [Hooks](#hooks) | | |
| 14 | | **External native loading** | Loading a third-party native plugin from disk at runtime | �� **Not wired yet** — discovery/manifest scaffolding exists (`src/plugins/discovery.zig`) but startup does not yet scan for or load external plugins | — | | |
| 15 | ||
| 16 | To ship a plugin to other people **without recompiling Den**, use the | |
| 17 | **WebAssembly** path. | |
| 18 | ||
| 19 | ### WebAssembly plugins | |
| 20 | ||
| 21 | A WASM plugin is any `wasm32-freestanding` module that exports the functions you | |
| 22 | want to call. Den runs them with a small built-in interpreter — no recompile and | |
| 23 | no host access (the module is sandboxed: it can compute and use its own linear | |
| 24 | memory, but cannot touch the filesystem, network, or environment). | |
| 25 | ||
| 26 | ```bash | |
| 27 | # Call an exported function: wasm <module.wasm> <export> [int-args...] | |
| 28 | den wasm math.wasm add 5 3 # => 8 | |
| 29 | ||
| 30 | # List a module's exported functions | |
| 31 | den wasm --exports math.wasm | |
| 32 | ``` | |
| 33 | ||
| 34 | **ABI (current):** arguments and the return value are integers (`i32`/`i64`); | |
| 35 | linear memory is available via `i32.load`/`i32.store`; floats are not supported. | |
| 36 | ||
| 37 | A complete, runnable example — source, a `plugin.manifest`, and build/run | |
| 38 | instructions — lives in [`examples/plugins/wasm/`](../examples/plugins/wasm/). | |
| 39 | ||
| 40 | ### The plugin manifest | |
| 41 | ||
| 42 | A plugin directory may include a `plugin.manifest` so tooling can describe the | |
| 43 | plugin without loading it. It is a simple `key = value` file (parsed by | |
| 44 | `src/plugins/discovery.zig`): | |
| 45 | ||
| 46 | ```ini | |
| 47 | name = math | |
| 48 | version = 1.0.0 | |
| 49 | description = Example WebAssembly plugin | |
| 50 | author = You | |
| 51 | license = MIT | |
| 52 | min_shell_version = 0.1 | |
| 53 | # dependency = othername:^1.0.0 | |
| 54 | # dependency = optionaldep:^2.0.0:optional | |
| 55 | ``` | |
| 56 | ||
| 57 | The remainder of this guide covers the **native, compiled-in** hook/command/ | |
| 58 | completion API. | |
| 59 | ||
| 5 | 60 | ## Table of Contents |
| 6 | 61 | |
| 7 | 62 | - [Overview](#overview) |
| @@ -0,0 +1,17 @@ | ||
| 1 | # Den plugin manifest (key = value). | |
| 2 | # Placed next to a plugin so Den can describe it without loading code. | |
| 3 | # Lines starting with '#' and blank lines are ignored. | |
| 4 | ||
| 5 | name = math | |
| 6 | version = 1.0.0 | |
| 7 | description = Example WebAssembly plugin exposing add, mul and fib | |
| 8 | author = Den | |
| 9 | license = MIT | |
| 10 | ||
| 11 | # Minimum Den version this plugin targets (optional). | |
| 12 | min_shell_version = 0.1 | |
| 13 | ||
| 14 | # Dependencies (optional, repeatable): | |
| 15 | # dependency = <name>:<version-req> | |
| 16 | # dependency = <name>:<version-req>:optional | |
| 17 | # (none for this example) | |