Shared crates for the xfetch ecosystem.
The current release line is 0.3.1. It keeps the JSON
protocol at version 1 and the WIT at
xfetch:runtime@0.1.0; the changes are additive.
crates/common(xfetch-api-common): shared protocol constants, frame shape, timeout and JSON IO helpers.crates/plugin-api: shared protocol crate for xfetch plugins.crates/extension-api: shared protocol crate for xfetch extensions (config providers).crates/effect-api: shared protocol crate for xfetch effects (intro animations over the info lines).crates/guest-api: host-call helpers for WebAssembly guests (http_request,exec,log,protocol_version).crates/command-api: shared protocol crate for CLI command addons.wit/xfetch-runtime.wit: component-model contract (plugin,effect,extensionandcommandworlds).docs/: focused documentation for setup, protocol, SDK usage, wasm guests, and examples.crates/*/examples/: minimal plugin, effect and extension binaries that compile against the public crates.
The first public crate in this repository is xfetch-plugin-api.
- Defines the wire protocol used between
xfetchand plugins. - Provides typed helpers for reading requests and writing responses.
- Exposes a stable base for official and third-party plugin development.
crates/effect-api (xfetch-effect-api) is the contract for
effects: installable intro animations. The core renders the info
lines and sends them to an effect binary (xfetch-effect-<name>);
the effect returns a sequence of frames (delay + transformed lines) that the core
plays before settling on the final content. Effect implementations are collected in
the xfetch-cli/effects repository
(the reference decrypt effect lives there).
- Request carries the rendered lines plus
style,duration_ms,fpsand free-formargs. - Response is a non-empty list of
EffectFrame { delay_ms, lines }. - Effects are opt-in: a missing binary or invalid response simply skips the intro (no behavior change).
crates/command-api (xfetch-command-api) is the
contract for CLI command addons. Commands receive arguments and return plain
text lines, so a command owns its own output format. Components use the
command world in the WIT package; core modules use the JSON
request on stdin and plain text on stdout.
- Documentation Index
- Getting Started
- Plugin SDK
- Protocol Reference
- Extension SDK
- Effect SDK
- Command SDK
- Examples
- This repository owns shared contracts, not end-user config files.
- Official plugins are expected to use the same public SDK as external plugins.
- Protocol changes should land here first and then be adopted by the core and plugin repos.
- Publishing order:
xfetch-api-commonfirst, thenxfetch-plugin-api,xfetch-extension-api,xfetch-effect-apiandxfetch-command-api;xfetch-guest-apiis independent.
The API crates are licensed under GPL-3.0-only, with an additional permission under GNU GPL version 3 section 7: addon code (plugins, extensions, effects or commands) that links or combines with the API is not required to be GPL and remains under the license declared by its author. This includes addons authored outside the xfetch project, including addons with external contributions. First-party addons authored by xscriptor are GPL-3.0-only. The API code itself, and modifications to it, remain GPL-3.0-only. Conveying a combined work still requires GPL compliance for the API portions. See LICENSE.