docs: bootstrap vault, roadmap and research

2026-10-17 21:14:19 +03:00
parent 749afadcd4
commit 8fa0632d69
34 changed files with 1508 additions and 0 deletions
@@ -0,0 +1,45 @@
+---
+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.