P2 — let the Zara flake consume and configure zara-plugins #228

New issue

Open

opened 2026-09-02 17:27:43 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-02 17:27:43 +00:00

Owner

Context

The public plugin registry (https://github.com/lost-rob0t/zara-plugins) is a flake. Its outputs, derived automatically from plugins.json:

per-plugin packages: packages.<system>.<name> (e.g. zara-avatar), installing the plugin tree under share/zara/plugins/<name>/ and the plugin CLI (when shipped) on bin/<name>;
aggregate: packages.<system>.zara-plugins — one tree with every registered plugin;
checks: registry validation plus each plugin's test suite (nix flake check on the registry);
install apps: nix run github:lost-rob0t/zara-plugins#zara-avatar -- install.

Downstream Nix users of Zara currently have no way to bring these plugins into a Zara closure: our mkZaraPackage wrappers only ship the core runtime, and plugin discovery reads [modules].search_paths (default ~/.zarathushtra/plugins), so store-installed plugins are never seen.

Goal

First-class flake plumbing so plugin installation and configuration are declarative, without weakening the imperative zara plugin install flow (tracked in #238).

Proposed design

Flake input: zara-plugins.url = "github:lost-rob0t/zara-plugins".
mkZaraPackage gains an extraPluginDirs (or pluginsEnv) parameter; wrappers prepend those directories to Zara's plugin search paths (env override or generated config fragment), so the plugin discovery/manager path is exercised unchanged.
Registry layout nuance to resolve here: the aggregate nests plugins under share/zara/plugins/<name>/... while iter_plugin_files scans only top-level *.py. The flake side should build a flattened discovery dir (symlinking each registered entrypoint into one directory) — or we extend discovery depth, but that decision belongs to this repo, not the registry.
Per-plugin configuration: provide a documented way to attach [plugins.<name>] settings from the flake (wrapper-level config.toml generation or overlay into the user's config), flowing through PluginManager's configuration_provider into PluginRuntime.configuration unchanged.
zara-avatar specifics: when its renderer gets reproducible Nix packaging, wire renderer_command (or ZARA_AVATAR_RENDERER) from the flake; until then the registry keeps renderer assets user-installed (tools/zara-avatar install).

Acceptance criteria

nix build .#<zara-package-with-plugins> produces a wrapper whose diagnostics show each enabled plugin discovered and RUNNING (or a precise failure state) at startup.
Per-plugin flake-provided configuration reaches runtime.configuration for that plugin.
No network during builds/checks; registry input is pinned via flake.lock like any other input.
Deterministic tests + nix flake check + scripts/test-all.sh green at exact head (TDD contract); wiki documents the Nix plugin story.

## Context The public plugin registry (https://github.com/lost-rob0t/zara-plugins) is a flake. Its outputs, derived automatically from `plugins.json`: - per-plugin packages: `packages.<system>.<name>` (e.g. `zara-avatar`), installing the plugin tree under `share/zara/plugins/<name>/` and the plugin CLI (when shipped) on `bin/<name>`; - aggregate: `packages.<system>.zara-plugins` — one tree with every registered plugin; - checks: registry validation plus each plugin's test suite (`nix flake check` on the registry); - install apps: `nix run github:lost-rob0t/zara-plugins#zara-avatar -- install`. Downstream Nix users of Zara currently have no way to bring these plugins into a Zara closure: our `mkZaraPackage` wrappers only ship the core runtime, and plugin discovery reads `[modules].search_paths` (default `~/.zarathushtra/plugins`), so store-installed plugins are never seen. ## Goal First-class flake plumbing so plugin installation and configuration are declarative, without weakening the imperative `zara plugin install` flow (tracked in #238). ## Proposed design 1. Flake input: `zara-plugins.url = "github:lost-rob0t/zara-plugins"`. 2. `mkZaraPackage` gains an `extraPluginDirs` (or `pluginsEnv`) parameter; wrappers prepend those directories to Zara's plugin search paths (env override or generated config fragment), so the plugin discovery/manager path is exercised unchanged. 3. Registry layout nuance to resolve here: the aggregate nests plugins under `share/zara/plugins/<name>/...` while `iter_plugin_files` scans only top-level `*.py`. The flake side should build a flattened discovery dir (symlinking each registered entrypoint into one directory) — or we extend discovery depth, but that decision belongs to this repo, not the registry. 4. Per-plugin configuration: provide a documented way to attach `[plugins.<name>]` settings from the flake (wrapper-level config.toml generation or overlay into the user's config), flowing through `PluginManager`'s `configuration_provider` into `PluginRuntime.configuration` unchanged. 5. zara-avatar specifics: when its renderer gets reproducible Nix packaging, wire `renderer_command` (or `ZARA_AVATAR_RENDERER`) from the flake; until then the registry keeps renderer assets user-installed (`tools/zara-avatar install`). ## Acceptance criteria - `nix build .#<zara-package-with-plugins>` produces a wrapper whose diagnostics show each enabled plugin discovered and RUNNING (or a precise failure state) at startup. - Per-plugin flake-provided configuration reaches `runtime.configuration` for that plugin. - No network during builds/checks; registry input is pinned via flake.lock like any other input. - Deterministic tests + `nix flake check` + `scripts/test-all.sh` green at exact head (TDD contract); wiki documents the Nix plugin story.

nsaspy added the

enhancement

label

2026-09-02 17:27:43 +00:00