From c3d1490443d92d514a8997dca610db6c5e552797 Mon Sep 17 00:00:00 2001 From: Hare Date: Mon, 15 Jun 2026 22:48:26 +0900 Subject: [PATCH] ticket: add plugin package resolver --- .yoi/tickets/00001KV5R5V2S/artifacts/.gitkeep | 0 .yoi/tickets/00001KV5R5V2S/item.md | 147 ++++++++++++++++++ .yoi/tickets/00001KV5R5V2S/thread.md | 7 + 3 files changed, 154 insertions(+) create mode 100644 .yoi/tickets/00001KV5R5V2S/artifacts/.gitkeep create mode 100644 .yoi/tickets/00001KV5R5V2S/item.md create mode 100644 .yoi/tickets/00001KV5R5V2S/thread.md diff --git a/.yoi/tickets/00001KV5R5V2S/artifacts/.gitkeep b/.yoi/tickets/00001KV5R5V2S/artifacts/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.yoi/tickets/00001KV5R5V2S/item.md b/.yoi/tickets/00001KV5R5V2S/item.md new file mode 100644 index 00000000..6764830f --- /dev/null +++ b/.yoi/tickets/00001KV5R5V2S/item.md @@ -0,0 +1,147 @@ +--- +title: 'Plugin: package discovery and explicit enablement resolver' +state: 'ready' +created_at: '2026-06-15T13:40:15Z' +updated_at: '2026-06-15T13:40:15Z' +assignee: null +readiness: 'implementation_ready' +risk_flags: ['plugin', 'package-loading', 'discovery', 'enablement', 'capability-boundary', 'startup-restore'] +--- + +## Background + +Plugin を利用可能にする最初の実装として、Plugin package を安全に発見・検査し、明示設定に基づいて enablement target として resolve できるようにする。 + +この Ticket では Plugin code の実行、Tool / Hook / Service / Ingress の登録、WASM runtime、`https` / `fs` host API 実装は行わない。package discovery と explicit enablement resolver を先に固め、後続の Plugin runtime / surface 実装が同じ解決結果を使えるようにする。 + +既存設計では以下を分離する。 + +```text +package discovery != enablement != runtime initialization != contribution registration +``` + +package が存在するだけで実行・登録されてはならない。Yoi は package を read-only に発見し、profile / config 側の明示 enablement entry と照合できるところまでをこの Ticket の範囲とする。 + +## Scope + +- Plugin package discovery +- Plugin package archive / directory safety validation +- `plugin.toml` manifest parsing +- Plugin package identity resolution +- Explicit enablement entry resolution +- Resolved Plugin metadata / diagnostics surface +- Startup / snapshot restore で再現可能な resolved input の保持または再構築方針 + +## Package locations + +最初の discovery source は以下を対象にする。 + +- User plugin store: + - `${XDG_DATA_HOME:-~/.local/share}/yoi/plugins/*.yoi-plugin` +- Workspace plugin store: + - `/.yoi/plugins/*.yoi-plugin` + +実装上、`.yoi-plugin` を archive として扱うか directory として扱うかは、既存設計 `00001KT0Z4BK8` を確認して合わせる。未実装部分がある場合は、最小実装を明示し、後続 Ticket で拡張できる構造にする。 + +## Requirements + +- Plugin package discovery は read-only とする。 + - 発見した package を実行しない。 + - Tool / Hook / Service / Ingress を登録しない。 + - package の存在だけで Plugin が有効化されない。 +- `plugin.toml` を package root から読み込む。 + - 必須 metadata を parse する。 + - unsupported / incompatible api version は fail closed にする。 +- Package safety checks を行う。 + - path traversal を reject する。 + - package root 外への symlink / escape を reject する。 + - bounded file count / total size / manifest size を設ける。 + - deterministic digest を計算する。 + - malformed package は diagnostic に残すが、Pod startup 全体を不要に壊さない。 +- Plugin identity を source-qualified に扱う。 + - `user:` + - `project:` + - `builtin:` +- Unqualified id が複数 source に一致する場合は ambiguous として fail closed にする。 +- Profile / config 側の explicit enablement entry を読む。 + - exact config location / shape は既存 Profile / plugin design に合わせ、必要なら最小の typed structure を追加する。 + - enablement entry は package ref、version / version constraint、digest pin、enabled surfaces、grant request / grant reference を表現できるようにする。 +- Enablement resolver は discovered package と enablement entry を照合する。 + - missing package + - duplicate package id + - ambiguous ref + - version mismatch + - digest mismatch + - incompatible api version + - requested surface unsupported + - grant missing / unsupported + を diagnostic として区別できるようにする。 +- Resolved Plugin は後続の runtime initialization / contribution registration に渡せる typed data として表す。 + - package identity + - source + - package path + - digest + - manifest metadata + - enabled surfaces + - effective grants / unresolved grants + - diagnostics +- Startup / snapshot restore で同じ resolved Plugin set を再現できること。 + - runtime-only mutable state に依存しない。 + - 必要な場合は Pod metadata / snapshot に resolved digest 等を含めるか、startup 時に deterministic に再解決する。 +- Diagnostics は model-visible context に勝手に差し込まない。 + - user-visible / logs / snapshot など既存の診断面に合わせる。 + - secret-like path / auth / file content を出さない。 + +## Non-goals + +- Plugin code execution。 +- WASM runtime 実装。 +- Tool / Hook / Service / Ingress の実登録。 +- `https` host API 実装。 +- `fs` host API 実装。 +- external network / filesystem side effect の実行。 +- plugin package manager / install / update / registry 実装。 +- package signature / trust chain 実装。 +- MCP bridge との統合。 + +## Acceptance criteria + +- User / workspace plugin store から `.yoi-plugin` package を発見できる。 +- Valid package の `plugin.toml` を parse し、typed manifest と deterministic digest を得られる。 +- Invalid package は fail closed し、bounded diagnostic として報告される。 +- Package が存在するだけでは Tool / Hook / Service / Ingress は登録されない。 +- Profile / config の explicit enablement entry なしでは Plugin は有効化されない。 +- Enablement entry と discovered package を照合し、resolved Plugin metadata を生成できる。 +- `user:` / `project:` / `builtin:` の source-qualified identity を扱える。 +- ambiguous unqualified id は fail closed する。 +- version mismatch / digest mismatch / incompatible api version / missing package が区別可能な diagnostic になる。 +- Startup / restore 時に resolved Plugin set が deterministic に再現できる。 +- Tests cover: + - valid user package discovery + - valid workspace package discovery + - package without enablement is not active + - explicit enablement resolves package + - duplicate / ambiguous id fail closed + - digest mismatch fail closed + - path traversal / root escape rejected + - unsupported api version rejected + - malformed manifest diagnostic + - no contribution registration from discovery-only path +- Validation: focused tests for plugin discovery/resolver, `cargo fmt --check`, relevant `cargo check` / `cargo test`, `git diff --check`, and `nix build .#yoi` if runtime resources / packaging / dependency graph change. + +## Implementation notes + +- Prefer adding a small typed Plugin package/resolver module rather than embedding resolver logic inside runtime launch code. +- Keep terminology aligned with the design record: + - Plugin runtime + - Plugin surface + - Plugin host API +- Do not reintroduce `contribution category` as user-facing terminology. +- Host APIs remain intentionally narrow. If this Ticket needs to mention APIs, use `https` and `fs`, not `web`. +- Discovery and enablement should integrate with the existing Profile / feature contribution direction without giving plugins ambient workspace filesystem authority. + +## Related work + +- `00001KSXRQ4G8` — Plugin runtime / surface / minimal host API model design. +- `00001KT0Z4BK8` — Plugin package / discovery format design. +- `00001KTR81P9X` — `pod::feature` API / plugin host substrate follow-up. diff --git a/.yoi/tickets/00001KV5R5V2S/thread.md b/.yoi/tickets/00001KV5R5V2S/thread.md new file mode 100644 index 00000000..1d40d945 --- /dev/null +++ b/.yoi/tickets/00001KV5R5V2S/thread.md @@ -0,0 +1,7 @@ + + +## 作成 + +LocalTicketBackend によって作成されました。 + +---