46 lines
2.4 KiB
Markdown
46 lines
2.4 KiB
Markdown
---
|
|
type: decision
|
|
adr: 002
|
|
status: accepted
|
|
date: 2026-10-17
|
|
supersedes:
|
|
tags: [adr, plugins, architecture]
|
|
---
|
|
|
|
# ADR-002: three-phase extension architecture (TOML → scripts → Lua)
|
|
|
|
## Context
|
|
viexp must let Linux users disable, replace and add file-type behaviors easily. Research
|
|
([[research/plugin-architecture]]) shows: declarative rules carry configuration, external
|
|
process contracts carry ~90% of real-world extension, and embedded interpreters are the most
|
|
expensive layer to stabilize (yazi is still "beta" partly because of it). WASM (zellij) costs
|
|
host complexity that a single-maintainer learning project cannot afford.
|
|
|
|
## Options considered
|
|
| Option | Pros | Cons |
|
|
|--------|------|------|
|
|
| Phased: TOML rules → script contract → Lua (mlua) | each phase shippable; users' language of choice; no unsafe early | three layers to document eventually |
|
|
| Lua from day 1 | yazi-grade power early | API design + FFI before first working product; high frustration risk |
|
|
| WASM components (wasmtime/extism) | best sandboxing | WIT churn, users must compile components; zellij-scale effort |
|
|
| External-only | simplest | no stateful in-process previews/fetchers ever |
|
|
|
|
## Decision (confirmed with the project owner, 2026-10-17)
|
|
1. **v0.1 — declarative registry**: `modules.toml` maps mime/glob → previewer/opener; per-module
|
|
`enabled` switch; user rules merge via `prepend_*`/`append_*` (yazi semantics). All built-in
|
|
modules dispatch through the same tables.
|
|
2. **v0.2 — external process contract (frozen, documented)**: previewer argv = `(path, width,
|
|
height, x, y)`; env context (mime, selection file, session dir); write-back via FIFO/socket
|
|
(nnn-style opcodes); `cleaner` hook; documented exit codes + SIGPIPE semantics.
|
|
Reference plugins in bash and Python ship in-repo.
|
|
3. **v1.0+ — embedded Lua** via **mlua with vendored Lua**, registered through the same tables;
|
|
only for what scripts cannot do (stateful/in-process previews). Re-evaluate Luau if sandbox
|
|
isolation becomes a requirement. **WASM is explicitly rejected for v1.x.**
|
|
|
|
## Consequences
|
|
- Positive: shippable increments; extension by Linux-familiar means; Lua postponed until the
|
|
host API is stable enough to expose.
|
|
- Negative: three layers of documentation eventually; write-back protocol must be designed
|
|
carefully once and frozen.
|
|
- Mitigations: one dispatch model for all layers (yazi lesson); contract docs written as part
|
|
of the v0.2 sprint DoD, not after.
|