# Lios Plugin Contract
Lios plugins are separate `lios-*` executables, not dynamically loaded shared
libraries. A plugin crash therefore cannot corrupt the terminal process, and
core Lios stays small.
## Preferences behavior
The `Plugins` card distinguishes three independent facts:
- managed: a binary and Cargo receipt exist in Lios's versioned plugin root and
pass ownership, permission, type, and pinned-identity checks;
- enabled: Lios may present and launch that plugin;
- running: a separately launched process may continue until it exits.
Enabling an absent plugin is an explicit install request. Lios invokes Cargo
directly with an argv equivalent to:
```text
cargo install --root "$XDG_DATA_HOME/lios/plugins/lios-bar-0.1.1" --locked --force --registry crates-io --version =0.1.1 lios-bar
```
No shell command string is built. The catalog supplies the crate name,
executable name, and exact version; user input cannot replace those fields.
Standard output is silenced. Standard error is continuously drained without
blocking Cargo, but Lios retains only a 32 KiB tail and shows at most 180
sanitized characters after a failure, so compiler output cannot grow memory
without limit or inject terminal control sequences into the GUI.
Cargo and its compiler children run in a dedicated process group. The install
button becomes `Cancel` while they run, closing the plugin UI also cancels the
operation, and a 30-minute safety deadline stops an abandoned build. Cancel and
timeout request graceful termination first, then kill the process group after a
five-second grace period if Cargo has not exited. Completion, cancellation, and
timeout callbacks share a generation guard so only the current install may
change its controls or configuration.
`XDG_DATA_HOME` falls back to `$HOME/.local/share`. Lios never discovers plugin
binaries through `PATH`; install, repair, detection, and launch all use that
fixed app-owned root.
After Cargo returns success, Lios requires the managed root, `bin` directory,
executable, and `.crates2.json` receipt to be real user-owned filesystem objects
rather than symlinks. They must reject group/world writes; the executable and
receipt must not be hard-linked; and the receipt is capped at 1 MiB. Its metadata
must match all of:
- curated crate name;
- exact curated version;
- registry source rather than a local path;
- expected executable name, with no second package claiming that binary.
A same-named or unsafe binary is shown as unmanaged and cannot be launched
through Lios until `Repair` installs the pinned registry release. Cargo's receipt
is an identity/provenance check, not a cryptographic signature of a locally built
binary; the managed-root checks prevent unrelated `PATH` entries from being
mistaken for official plugins.
Disabling changes only `[plugins]` in the Lios config. It never runs
`cargo uninstall`, removes files, deletes plugin data, or terminates a process
that the user already launched. No plugin is installed, repaired, updated, or
launched in the background.
## Configuration
Plugin enablement is stored atomically with user-only config permissions:
```toml
[plugins]
lios_bar = true
```
Malformed non-boolean values fail configuration validation. Unknown
lowercase plugin keys are preserved so a newer Lios release can add catalog
entries without an older release deleting their state.
## Adding an official plugin
A catalog entry must remain a compile-time constant and include a unique
lowercase config key, crates.io package name, executable name, exact reviewed
version, display name, description, and a bounded safe launch contract.
Before catalog inclusion, the plugin must:
- be published under `MIT OR Apache-2.0` with both canonical license files and
explicit Trevor Knott/Knott Dynamics attribution;
- publish a locked crate containing its README and security documentation;
- accept `--version` and `--help` without side effects;
- avoid listening sockets, telemetry, credentials, and automatic downloads
unless those capabilities are the plugin's clearly documented purpose;
- pass formatting, strict Clippy, tests, package verification, and an install
smoke test from the exact public artifact.
Plugins needing destinations, credentials, terminal byte streams, or service
lifecycles require a purpose-built UI and threat model. They must not reuse the
standalone launch contract merely to appear in the catalog.