beeui 0.13.0__py3-none-any.whl

beeui-0.13.0.dist-info/METADATA

@@ -0,0 +1,1709 @@
+Metadata-Version: 2.4
+Name: beeui
+Version: 0.13.0
+Summary: Reusable UI framework for Bee products
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.135
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pydantic>=2.11
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: uvicorn>=0.44
+Provides-Extra: dev
+Requires-Dist: httpx2>=2.2.0; extra == "dev"
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+
+# BeeUI — reusable UI framework для Bee-продуктов
+
+**BeeUI** — общий Python-based UI framework для Bee-продуктов: `beecap`, `beeagent` и будущих модулей Bee ecosystem.
+
+## Iteration 11
+
+Текущий deliverable — Generic artifact browser v1: read-only просмотр артефактов через `ProductUiAdapter`.
+
+Уже работает:
+
+- всё из Iteration 10: `create_beeui_app(...)`, `mount_beeui(...)`, adapter injection, product metadata, mount path validation;
+- `uv sync --frozen --extra dev`;
+- `uv run pytest -q`;
+- `./start.sh doctor`;
+- `./start.sh version`;
+- `./start.sh routes`;
+- `./start.sh web --host 127.0.0.1 --port 8780`;
+- `import beeui_module`;
+- schema-driven theme/layout/navigation в `config/schema.yml`;
+- schema-driven literal и resolver-backed blocks в `config/schema.yml`;
+- read-only `demo` data source;
+- read-only `static` YAML/JSON data source;
+- stable resolver envelope для controlled block value resolution;
+- dashboard blocks рендерятся из top-level `blocks` и `pages[].blocks[]`;
+- generic adapter contract package `src/beeui_module/adapters/`;
+- stable adapter envelopes (`ok|partial|error`) and stable adapter errors;
+- safe adapter ID helpers for `product_id`, `run_id`, `artifact_id`, `action_id`;
+- BeeCap-compatible fixture adapter `BeeCapFixtureAdapter`;
+- controlled BeeCap-like fixtures under `tests/fixtures/beecap/`;
+- BeeCap adapter fixture tests in `tests/test_beecap_adapter.py`;
+- integration boundary docs in `docs/INTEGRATION.md`;
+- embedded BeeCap example in `examples/beecap_embedded/beeui.yml`;
+- `GET /runs/{run_id}/artifacts` — HTML список артефактов;
+- `GET /runs/{run_id}/artifacts/{artifact_id}` — HTML preview артефакта;
+- `GET /api/runs/{run_id}/artifacts` — JSON API список артефактов;
+- `GET /api/runs/{run_id}/artifacts/{artifact_id}` — JSON API preview артефакта;
+- JSON preview с redaction;
+- JSONL preview до 500 строк с row-level warnings;
+- text preview до 100 000 символов;
+- unsupported/binary artifacts отображаются как metadata-only;
+- malformed JSON/JSONL не ломают страницу/API;
+- large JSON/JSONL preview ограничен 512 KB;
+- safe `run_id` / `artifact_id` validation;
+- redaction placeholder для `secret`, `token`, `password`, `api_key`, `api_secret`;
+- доступ к артефактам идёт только через `ProductUiAdapter.list_artifacts()` и `ProductUiAdapter.read_artifact()`;
+- при отсутствии adapter возвращается explicit 503 unavailable state;
+- `features.browser_artifact` включает/отключает HTML/API artifact routes;
+- `features.api` остаётся зарезервированным для будущего stable BeeUI API и не отключает artifact browser API routes;
+- `create_beeui_app(settings, ui_config, *, config_path, product_id, product_title, adapter)`;
+- `mount_beeui(parent_app, *, path, ...)` для встраивания BeeUI в родительское FastAPI приложение;
+- `app.state.beeui_adapter` — сохранение adapter instance;
+- `app.state.beeui_product` — сохранение product metadata;
+- runtime-валидация adapter на соответствие минимальному протоколу `ProductUiAdapter`;
+- валидация mount path (безопасный путь, без path traversal);
+- проверка коллизии маршрутов при mount;
+- embedded API тесты в `tests/test_embedded.py`.
+
+Поддерживаемые типы блоков:
+
+- `metric_card`;
+- `kpi_grid`;
+- `status_card`;
+- `table_card`;
+- `links_card`;
+- `alert_card`;
+- `text_card`;
+- `progress_card`.
+
+Минимальная web surface после Iteration 11:
+
+- `GET /`
+- `GET /runs`
+- `GET /components`
+- `GET /components/interface`
+- `GET /components/forms`
+- `GET /components/layout`
+- `GET /components/extra`
+- `GET /components/plugins`
+- `GET /health`
+- `GET /static/...`
+- `GET /static/vendor/tabler/css/tabler-compatible.min.css`
+- `GET /static/vendor/tabler/js/tabler-compatible.min.js`
+- `GET /runs/{run_id}/artifacts`
+- `GET /runs/{run_id}/artifacts/{artifact_id}`
+- `GET /api/runs/{run_id}/artifacts`
+- `GET /api/runs/{run_id}/artifacts/{artifact_id}`
+
+При использовании `mount_beeui(parent, path="/ui")` маршруты доступны под `/ui/`:
+
+- `GET /ui/`
+- `GET /ui/health`
+- `GET /ui/static/...`
+- `GET /ui/runs/{run_id}/artifacts`
+- `GET /ui/runs/{run_id}/artifacts/{artifact_id}`
+- `GET /ui/api/runs/{run_id}/artifacts`
+- `GET /ui/api/runs/{run_id}/artifacts/{artifact_id}`
+
+Iteration 11 добавляет только read-only artifact API routes. Stable BeeUI API для dashboard/runs/config/actions остаётся future scope.
+
+Shell и dashboard рендерятся через component templates:
+
+- `components/sidebar.html`;
+- `components/navbar.html`;
+- `components/page_header.html`;
+- `components/footer.html`;
+- `components/empty_state.html`.
+- block component templates для literal и resolver-backed dashboard blocks.
+
+Tabler-compatible vendor assets поставляются локально из package path:
+
+- `src/beeui_module/web/static/vendor/tabler/css/tabler-compatible.min.css`
+- `src/beeui_module/web/static/vendor/tabler/js/tabler-compatible.min.js`
+
+BeeUI поставляет локальный Tabler-compatible subset в
+`src/beeui_module/web/static/vendor/tabler/`.
+Это не полный upstream Tabler demo bundle.
+Preview/demo/tracking assets не поставляются.
+
+Navigation, theme и layout shell options (title/subtitle/paths/logo_text/theme/layout) рендерятся из `config/schema.yml`.
+
+Пока не входит в scope:
+
+- production BeeCap/BeeAgent adapters;
+- adapter-backed dashboard/runs rendering (Iteration 12+);
+- run detail page;
+- stable BeeUI API для dashboard/runs/config/actions;
+- auth/session;
+- config UI;
+- no-code builder.
+
+Проект нужен, чтобы не писать заново в каждом продукте:
+
+- web shell;
+- sidebar / navbar / layout;
+- dashboard;
+- KPI cards;
+- tables;
+- artifact browser;
+- config UI;
+- operator/admin pages;
+- theme customization;
+- bounded operator actions;
+- стабильный read-only JSON API для будущего frontend.
+
+BeeUI строится как reusable layer поверх:
+
+- **FastAPI** — web runtime;
+- **Jinja2** — server-rendered HTML templates;
+- **Tabler** — UI/admin visual foundation;
+- **Pydantic / dataclasses** — schema/config/read-model contracts;
+- **file/API adapters** — подключение к Bee-продуктам.
+
+BeeUI не является trading engine, agent runtime или backend core. Он не принимает domain-решения и не получает прямую execution authority.
+
+Главное правило:
+
+```text
+BeeUI renders.
+Product decides.
+```
+
+## Зачем нужен BeeUI
+
+Сейчас `beecap` и `beeagent` начинают дублировать один и тот же UI-слой:
+
+- разные web directories;
+- разные templates;
+- разные CSS;
+- разные dashboards;
+- разные artifact viewers;
+- разные admin/config pages;
+- разные operator controls.
+
+Это быстро превращается в хаос.
+
+BeeUI решает эту проблему как общий UI/runtime package:
+
+```text
+beecap
+  -> exposes read-model / artifacts / bounded actions
+  -> BeeUI renders dashboard, runs, artifacts, config/admin pages
+
+beeagent
+  -> exposes modules / runs / capabilities / artifacts
+  -> BeeUI renders operator console and будущий frontend shell
+```
+
+## Текущий фокус проекта
+
+Текущий фокус BeeUI:
+
+- быстро дойти до MVP;
+- подключить `beecap` как первый продукт;
+- перестать расширять кастомный web UI внутри `beecap`;
+- затем подключить `beeagent`;
+- сохранить KISS, безопасность и read-only по умолчанию;
+- подготовить основу для будущего no-code dashboard/frontend builder.
+
+MVP не пытается сразу стать полноценным Retool/Webflow/Admin SaaS.
+
+Целевой MVP делает controlled declarative console:
+
+- pages описываются через schema/config;
+- blocks описываются через schema/config;
+- данные приходят из product adapter;
+- artifacts отображаются через bounded artifact browser;
+- write/control actions идут только через product-owned callbacks.
+
+## Что BeeUI делает
+
+В текущем состоянии после Iteration 11 BeeUI отвечает за:
+
+- FastAPI app factory;
+- Jinja2 templates;
+- Tabler layout;
+- global navigation;
+- reusable blocks;
+- dashboard rendering;
+- declarative pages/navigation/theme/layout;
+- static/literal and resolver-backed dashboard blocks from `config/schema.yml`;
+- generic product adapter contract v0 in `src/beeui_module/adapters/`;
+- BeeCap-compatible fixture/reference adapter for contract validation;
+- embedded app factory `create_beeui_app(...)`;
+- mount helper `mount_beeui(...)`;
+- загрузку product-specific UI config через `config_path`;
+- product metadata injection;
+- adapter injection, validation и сохранение в `app.state.beeui_adapter`;
+- сохранение product metadata в `app.state.beeui_product`;
+- проверку mount path и route collision guard;
+- artifact browser — HTML/JSON list and preview через adapter;
+- JSON/JSONL/text bounded preview с malformed handling, preview limits и redaction;
+- read-only API routes для артефактов.
+
+Запланированные обязанности:
+
+- runs list / run detail pages;
+- source artifact links;
+- config read-model;
+- config preview/apply framework;
+- bounded operator actions;
+- auth/session layer;
+- theme customization;
+- stable JSON API для будущего frontend;
+- standalone mode.
+
+## Чего BeeUI не делает
+
+BeeUI не должен:
+
+- принимать торговые решения;
+- запускать broker/API calls напрямую;
+- читать secrets;
+- менять runtime state без product callback;
+- самостоятельно парсить domain logic BeeCap/BeeAgent;
+- становиться вторым source of truth;
+- заменять `config/settings.yml` продукта;
+- заменять `storage/` artifacts продукта;
+- исполнять live/broker actions;
+- делать hidden fallback execution;
+- обходить product validation/security boundaries.
+
+Все domain-sensitive вещи остаются в продукте.
+
+## Интеграционная модель
+
+### MVP: embedded mode
+
+Для MVP BeeUI подключается как dependency внутрь продукта.
+
+```text
+beecap process
+  imports beeui
+  creates BeeCapUiAdapter
+  mounts BeeUI FastAPI app
+```
+
+Для BeeAgent это пока будущий scope. Целевая структура может быть похожей:
+
+```text
+beeagent process
+  imports beeui
+  creates BeeAgentUiAdapter
+  mounts BeeUI FastAPI app
+```
+
+Плюсы:
+
+- быстро;
+- один процесс;
+- проще локальная разработка;
+- проще auth/session;
+- нет CORS;
+- нет отдельного service discovery;
+- меньше deployment complexity.
+
+Минусы:
+
+- каждый продукт запускает свой BeeUI instance;
+- обновление BeeUI идёт через dependency update.
+
+### Будущий `standalone` mode
+
+Позже BeeUI сможет работать отдельным сервисом:
+
+```text
+beeui service
+  -> connects to beecap API
+  -> connects to beeagent API
+  -> renders multi-product UI
+```
+
+Плюсы:
+
+- один UI service;
+- можно сделать unified Bee dashboard;
+- проще отдельный frontend;
+- можно держать `beecap` и `beeagent` как backend/API services.
+
+Минусы:
+
+- сложнее auth;
+- CORS;
+- network timeouts;
+- service discovery;
+- deployment complexity.
+
+Решение:
+
+```text
+MVP: embedded.
+Позже: standalone.
+```
+
+## Как подключать к BeeCap
+
+На этапе разработки `beeui` лежит рядом:
+
+```text
+~/Projects/
+  beecap/
+  beeagent/
+  beeui/
+```
+
+В `beecap/pyproject.toml` для локальной разработки:
+
+```toml
+dependencies = [
+    "beeui @ file:///home/bee/Projects/beeui",
+]
+```
+
+Или временно:
+
+```bash
+cd ~/Projects/beecap
+uv pip install -e ../beeui
+```
+
+Целевой вариант после стабилизации:
+
+```toml
+dependencies = [
+    "beeui @ git+ssh://git@github.com/beesyst/beeui.git@v0.1.0",
+]
+```
+
+Минимальный integration point в BeeCap:
+
+```text
+src/beecap_module/interfaces/ui/
+  adapter.py
+  read_model.py
+  artifacts.py
+  actions.py
+```
+
+BeeCap adapter отвечает за:
+
+- dashboard read-model;
+- runs list;
+- run detail;
+- artifact allowlist;
+- artifact reading;
+- config read-model;
+- config validation callback;
+- bounded action callbacks.
+
+BeeUI не должен напрямую знать внутреннюю trading-логику BeeCap.
+
+## Как подключать к BeeAgent
+
+BeeAgent integration — будущий scope. Ниже оставлена только минимальная целевая структура, чтобы не создавать впечатление готовой реализации.
+
+Целевой integration point:
+
+```text
+src/beeagent_module/interfaces/ui/
+  adapter.py
+  read_model.py
+  artifacts.py
+  capabilities.py
+  actions.py
+```
+
+BeeAgent adapter отвечает за:
+
+- dashboard read-model;
+- modules;
+- runs;
+- artifacts;
+- capabilities;
+- approvals;
+- bounded actions;
+- authority/capability checks.
+
+BeeUI не должен получать прямую authority на tools/MCP/runtime actions.
+
+## Режимы работы BeeUI
+
+### `demo`
+
+Локальный demo mode.
+
+Используется для разработки BeeUI без BeeCap/BeeAgent.
+
+```bash
+./start.sh web
+```
+
+Вариант с явным host/port:
+
+```bash
+./start.sh web --host 127.0.0.1 --port 8780
+```
+
+Что показывает:
+
+- schema-driven demo pages;
+- schema-driven navigation;
+- schema-driven theme/layout;
+- static/literal и resolver-backed dashboard blocks из `config/schema.yml`;
+- controlled read-only `demo` data source;
+- controlled read-only `static` YAML/JSON data source;
+- empty state для pages без block placements.
+
+### `embedded`
+
+Основное направление MVP integration.
+
+Продукт импортирует BeeUI и монтирует его в своём web process.
+
+Текущий статус после Iteration 11:
+
+- generic adapter contract существует;
+- BeeCap fixture/reference adapter существует для contract validation;
+- production BeeCap adapter остаётся ответственностью BeeCap-side;
+- `create_beeui_app(...)` accepts `config_path`, product metadata and adapter;
+- `mount_beeui(...)` mounts BeeUI into parent FastAPI app;
+- adapter is validated and stored in `app.state.beeui_adapter`;
+- product metadata is stored in `app.state.beeui_product`;
+- artifact browser routes уже используют adapter для `list_artifacts()` и `read_artifact()`;
+- `/api/runs/{run_id}/artifacts*` routes доступны при `features.browser_artifact: true`;
+- adapter-backed dashboard/runs rendering остаётся future scope.
+
+Embedded example:
+
+```python
+from beeui_module.web.app import create_beeui_app
+from beecap_module.interfaces.ui.adapter import BeeCapUiAdapter
+
+app = create_beeui_app(
+    product_id="beecap",
+    product_title="BeeCap",
+    adapter=BeeCapUiAdapter(...),
+    config_path="config/beeui.yml",
+)
+```
+
+### `standalone`
+
+Будущий scope.
+
+В текущем MVP standalone mode не реализован. Запуск с отдельным config-файлом будет добавлен позже, когда появится HTTP product adapter и standalone deployment contract.
+
+## Основные возможности
+
+### Declarative pages
+
+Страницы задаются через config/schema.
+
+```yaml
+blocks:
+  latest_run:
+    type: metric_card
+    title: Latest Run
+    value: run_demo_001
+    subtitle: Static demo value
+
+pages:
+  - id: dashboard
+    path: /
+    title: Dashboard
+    subtitle: Demo operator dashboard
+    blocks:
+      - block: latest_run
+        width: 3
+```
+
+Текущие declarative page rules:
+
+- `page.id` must be unique;
+- `page.path` must be unique;
+- `navigation[].path` must reference declared page path;
+- reserved paths `/health`, `/static`, `/static/...` are rejected;
+- `blocks` in page config is a list of block placements;
+- each placement references a top-level block id;
+- `width` must be an integer from `1` to `12`;
+- unknown block references are rejected fail-fast.
+
+### Blocks
+
+Текущий block contract после Iteration 7 поддерживает literal fields и resolver-backed fields из controlled read-only `demo` / `static` data sources.
+
+Top-level `blocks` defines reusable block definitions.
+`pages[].blocks[]` defines where these blocks appear on a page.
+
+Сейчас поддерживаются типы блоков:
+
+- `metric_card`;
+- `kpi_grid`;
+- `status_card`;
+- `table_card`;
+- `links_card`;
+- `alert_card`;
+- `text_card`;
+- `progress_card`.
+
+Пример:
+
+```yaml
+blocks:
+  latest_run:
+    type: metric_card
+    title: Latest Run
+    value: run_demo_001
+    subtitle: Static demo value
+
+  runtime_status:
+    type: status_card
+    title: Runtime
+    status: ok
+    value: Ready
+
+pages:
+  - id: dashboard
+    path: /
+    title: Dashboard
+    subtitle: Demo operator dashboard
+    blocks:
+      - block: latest_run
+        width: 3
+      - block: runtime_status
+        width: 3
+```
+
+Текущие правила:
+
+- block ids must be safe identifiers;
+- unknown block types are rejected;
+- unknown block references are rejected;
+- renderer-specific fields are validated fail-fast;
+- text values are rendered through Jinja autoescape;
+- no arbitrary HTML/JS/CSS from config;
+- `links_card.href` accepts internal safe paths only;
+- display values may be literal scalars or resolver-backed values from controlled demo/static sources;
+- missing/empty page placements render an empty state.
+
+Реализовано в Iteration 7:
+
+- read-only data resolver;
+- selector syntax with dot path and optional `[index]` lookup;
+- `demo` source;
+- `static` YAML/JSON source;
+- stable resolver envelope;
+- degraded block rendering on missing selector data.
+
+Пока не реализовано:
+
+- production BeeCap/BeeAgent adapters;
+- adapter-backed block data in runtime;
+- charts/maps;
+- artifact/config/action blocks;
+- arbitrary HTML/JS blocks.
+
+### Data sources
+
+Iteration 7 поддерживает controlled read-only data sources в `config/schema.yml`.
+Текущие supported source types:
+
+- `demo`
+- `static` with `format: yaml|json` and a safe relative `path`
+
+Resolver envelope:
+
+```json
+{
+  "status": "ok|partial|error",
+  "data": {},
+  "warnings": [
+    {
+      "code": "selector_missing",
+      "message": "Selector not found: dashboard.latest_run.id"
+    }
+  ],
+  "source": {
+    "type": "demo|static|unknown",
+    "id": "demo_dashboard"
+  }
+}
+```
+
+Текущая block schema остаётся backward-compatible: literal fields продолжают работать, resolver-backed fields опциональны.
+Adapter-backed data sources остаются будущим scope и не входят в текущие runtime source types Iteration 7.
+
+Resolver-backed block example:
+
+```yaml
+data_sources:
+  demo_dashboard:
+    type: demo
+
+blocks:
+  latest_run:
+    type: metric_card
+    title: Latest Run
+    source: demo_dashboard
+    value_selector: dashboard.latest_run.id
+    subtitle_selector: dashboard.latest_run.status
+```
+
+Resolver envelope — внутренний block data-resolution contract в Iteration 7.
+Это ещё не public `/api/*` route contract.
+Public BeeUI JSON API запланирован для следующих итераций.
+
+### Product adapters
+
+Product adapter contract реализован в Iteration 8 как generic boundary в `src/beeui_module/adapters/`.
+
+Scope Iteration 8:
+
+- generic `ProductUiAdapter` protocol/base contract;
+- stable adapter envelopes for `ok|partial|error`;
+- stable adapter error classes and error envelope helper;
+- safe id validation helpers;
+- optional write/action methods are disabled by default.
+
+Non-goals Iteration 8:
+
+- no production BeeCap adapter;
+- no concrete BeeAgent adapter;
+- no direct product filesystem crawling;
+- public route surface не менялся в Iteration 8;
+- no direct execution authority.
+
+Iteration 9 добавляет BeeCap fixture/reference adapter support:
+
+- `BeeCapFixtureAdapter` validates BeeCap-shaped dashboard/runs/artifact-reference payloads;
+- fixtures live under `tests/fixtures/beecap/`;
+- this adapter is not a production BeeCap integration;
+- real BeeCap adapter must live on the BeeCap side under `src/beecap_module/interfaces/ui/`;
+- Iteration 10 добавила app factory adapter injection и `mount_beeui(...)`;
+- Iteration 11 добавила adapter-backed artifact browser routes;
+- adapter-backed dashboard/runs rendering остаётся future scope.
+
+Текущий contract v0 после Iteration 8:
+
+```python
+class ProductUiAdapter:
+  # required read-only
+  def get_dashboard(self) -> dict: ...
+  def list_runs(self) -> dict: ...
+  def get_run(self, run_id: str) -> dict: ...
+  def list_artifacts(self, run_id: str) -> dict: ...
+  def read_artifact(self, run_id: str, artifact_id: str) -> dict: ...
+  def get_config_read_model(self) -> dict: ...
+
+  # optional, unavailable by default
+  def validate_config_candidate(self, candidate: dict) -> dict: ...
+  def list_actions(self) -> dict: ...
+  def preview_action(self, action_id: str, payload: dict) -> dict: ...
+  def execute_action(self, action_id: str, payload: dict) -> dict: ...
+```
+
+После Iteration 11 BeeUI вызывает adapter через embedded mount/app factory layer для artifact browser routes.
+
+Product adapter решает, что можно читать/делать.
+
+## Artifact browser
+
+BeeUI предоставляет generic artifact browser после Iteration 11.
+
+Он отображает:
+
+- JSON;
+- JSONL;
+- text;
+- metadata;
+- parse warnings;
+- source links;
+- partial/corrupted state.
+
+Правила:
+
+- только allowlisted artifacts;
+- никакого arbitrary filesystem browsing;
+- path traversal заблокирован;
+- source artifacts не мутируются;
+- secrets redacted;
+- corrupted artifacts не ломают page.
+
+Routes:
+
+```text
+GET /runs/{run_id}/artifacts
+GET /runs/{run_id}/artifacts/{artifact_id}
+GET /api/runs/{run_id}/artifacts
+GET /api/runs/{run_id}/artifacts/{artifact_id}
+```
+
+## Config UI
+
+BeeUI должен дать reusable config UI layer, но не владеть config source of truth.
+
+Source of truth остаётся в продукте:
+
+```text
+beecap/config/settings.yml
+beeagent/config/settings.yml
+```
+
+BeeUI config UI работает через product adapter.
+
+### Read-model
+
+```text
+GET /config
+GET /api/config/read-model
+```
+
+Показывает:
+
+- editable fields;
+- non-editable fields;
+- redacted fields;
+- current values;
+- validation metadata;
+- constraints/options.
+
+### Preview
+
+```text
+POST /api/config/preview
+```
+
+Semantics:
+
+- build candidate config in memory;
+- call product validation callback;
+- return diff + validation result;
+- no file writes.
+
+### Apply
+
+```text
+POST /api/config/apply
+```
+
+Semantics:
+
+- only allowlisted keys;
+- stale config hash guard;
+- validate candidate through product validation callback;
+- backup current config;
+- write canonical product config;
+- create audit artifact;
+- no secrets in audit;
+- no runtime restart hidden behind apply.
+
+Suggested artifacts:
+
+```text
+storage/interfaces/config_revisions/<change_id>/settings.before.yml
+storage/interfaces/config_changes/<change_id>/audit.json
+```
+
+## Operator actions
+
+BeeUI can show bounded operator actions, but action execution belongs to the product.
+
+Example actions:
+
+- start allowed preset;
+- refresh index;
+- run doctor;
+- create report;
+- open artifact;
+- create draft;
+- approve safe internal action.
+
+Forbidden by default:
+
+- broker manual order;
+- direct live execution;
+- secret editing;
+- arbitrary shell command;
+- arbitrary config mutation;
+- runtime kill/restart unless product explicitly exposes bounded callback.
+
+All action attempts should create audit artifacts:
+
+```text
+storage/interfaces/operator_actions/<action_id>.json
+```
+
+## Auth and roles
+
+BeeUI auth layer запланирован после MVP dashboard integration.
+
+Initial roles:
+
+| Role       | Meaning                                            |
+| ---------- | -------------------------------------------------- |
+| `viewer`   | read-only UI access                                |
+| `operator` | read-only + bounded allowed actions                |
+| `admin`    | config/admin actions inside allowlisted boundaries |
+
+Security rules:
+
+- auth disabled only explicitly for local/dev;
+- no default admin password in repo;
+- password hash only;
+- signed session cookies;
+- CSRF protection for POST routes;
+- no secrets in logs;
+- no secrets in HTML/API.
+
+## Theme customization
+
+BeeUI theme config:
+
+```yaml
+app:
+  theme:
+    mode: dark
+    primary: blue
+    font: Inter
+    radius: 2
+    density: compact
+```
+
+Поддерживаемая кастомизация:
+
+- dark/light;
+- primary color;
+- font family;
+- border radius;
+- density;
+- product title;
+- logo;
+- favicon;
+- compact mode.
+
+Forbidden by default:
+
+- arbitrary CSS editor;
+- arbitrary JS;
+- unsafe HTML injection;
+- user-uploaded executable assets.
+
+## Технологический стек
+
+- **Python 3.14+**
+- **src-layout** — пакет `beeui_module` в `src/`
+- **FastAPI** — web runtime
+- **Jinja2** — templates
+- **Tabler** — dashboard/admin UI foundation
+- **PyYAML** — config/schema files
+- **pytest** — тесты
+- **httpx** — web route tests
+- **uv** — dependency/install/runtime workflow
+- **file-based artifacts** — для audits/examples/demo
+- **future**: optional standalone HTTP adapter
+
+## Управление и запуск
+
+Запуск — через `start.sh`.
+
+### Установка
+
+После clone:
+
+```bash
+git clone git@github.com:beesyst/beeui.git
+cd beeui
+./start.sh doctor
+```
+
+`start.sh`:
+
+- проверяет наличие `uv`;
+- если `uv` отсутствует — устанавливает его;
+- ставит зависимости из `uv.lock`;
+- запускает `config/start.py`;
+- не должен скрыто менять runtime contracts.
+
+### Команды
+
+```bash
+./start.sh doctor
+```
+
+Проверяет:
+
+- Python version;
+- package import;
+- config files;
+- templates/static availability;
+- basic environment.
+
+```bash
+./start.sh web
+```
+
+Запускает demo BeeUI web app.
+
+```bash
+./start.sh web --host 127.0.0.1 --port 8780
+```
+
+Запускает demo web app на конкретном host/port.
+
+```bash
+./start.sh routes
+```
+
+Показывает registered routes.
+
+```bash
+./start.sh version
+```
+
+Показывает версию BeeUI.
+
+---
+
+## Локальная разработка
+
+### Установка зависимостей
+
+```bash
+uv sync --frozen --extra dev
+```
+
+### Тесты
+
+```bash
+uv run pytest -q
+```
+
+### Запуск demo UI
+
+```bash
+./start.sh web --host 127.0.0.1 --port 8780
+```
+
+Открыть:
+
+```text
+http://127.0.0.1:8780
+```
+
+### Без `start.sh`
+
+```bash
+uv run --frozen --extra dev python config/start.py doctor
+uv run --frozen --extra dev python config/start.py web
+```
+
+## Документация
+
+Основная документация проекта находится в `docs/`.
+
+Ключевые разделы:
+
+- `docs/ROADMAP.md` — этапы и итерации;
+- `docs/SDLC.md` — lightweight process, checks, PR workflow;
+- `docs/SECURITY.md` — secure development rules;
+- `docs/WEB_UI.md` — HTML routes, layout, dashboard behavior;
+
+## Целевая структура проекта
+
+Актуальные ключевые файлы после Iteration 11:
+
+```text
+config/
+  settings.yml
+  schema.yml
+
+docs/
+  INTEGRATION.md
+
+examples/
+  beecap_embedded/
+    beeui.yml
+
+tests/
+  fixtures/
+    beecap/
+
+src/beeui_module/
+  blocks/
+    __init__.py
+    models.py
+    registry.py
+    renderers.py
+  cli/
+    doctor.py
+    main.py
+    web.py
+  core/
+    paths.py
+    settings.py
+    log.py
+    version.py
+  data/
+    __init__.py
+    models.py
+    resolver.py
+    selectors.py
+    sources.py
+  adapters/
+    __init__.py
+    base.py
+    envelopes.py
+    errors.py
+    ids.py
+    beecap.py
+  artifacts/
+    __init__.py
+    models.py
+    preview.py
+    redaction.py
+    routes.py
+  pages/
+    config.py
+    models.py
+    router.py
+  web/
+    app.py
+    templates/
+      base.html
+      page.html
+      components/
+        alert_card.html
+        footer.html
+        kpi_grid.html
+        links_card.html
+        metric_card.html
+        navbar.html
+        page_header.html
+        progress_card.html
+        sidebar.html
+        status_card.html
+        table_card.html
+        text_card.html
+        empty_state.html
+      artifacts/
+        list.html
+        detail.html
+    static/
+      css/beeui.css
+      js/beeui.js
+      vendor/
+        tabler/
+          css/tabler-compatible.min.css
+          js/tabler-compatible.min.js
+```
+
+Остальная структура ниже — целевая для следующих итераций.
+
+```text
+beeui/
+├── config/
+│   ├── settings.yml
+│   └── start.py
+│
+├── docs/
+│   ├── API_CONTRACT.md
+│   ├── COMPONENTS.md
+│   ├── INTEGRATION.md
+│   ├── ROADMAP.md
+│   ├── SDLC.md
+│   ├── SECURITY.md
+│   ├── THEME.md
+│   └── WEB_UI.md
+│
+├── examples/
+│   ├── demo_static/
+│   ├── beecap_embedded/
+│   └── beeagent_embedded/
+│
+├── logs/
+│   └── app.log
+│
+├── src/
+│   └── beeui_module/
+│       ├── __init__.py
+│       ├── config.py
+│       ├── errors.py
+│       ├── server.py
+│       ├── settings.py
+│       │
+│       ├── api/
+│       │   ├── envelopes.py
+│       │   └── routes.py
+│       │
+│       ├── artifacts/
+│       │   ├── browser.py
+│       │   ├── models.py
+│       │   ├── readers.py
+│       │   └── safe_paths.py
+│       │
+│       ├── auth/
+│       │   ├── models.py
+│       │   ├── password.py
+│       │   ├── permissions.py
+│       │   ├── routes.py
+│       │   ├── service.py
+│       │   └── sessions.py
+│       │
+│       ├── adapters/
+│       │   ├── base.py
+│       │   ├── filesystem.py
+│       │   ├── http.py
+│       │   ├── product.py
+│       │   ├── beecap.py
+│       │   └── beeagent.py
+│       │
+│       ├── blocks/
+│       │   ├── models.py
+│       │   ├── registry.py
+│       │   ├── renderers.py
+│       │   └── types/
+│       │       ├── artifact_table.py
+│       │       ├── chart_card.py
+│       │       ├── json_viewer.py
+│       │       ├── kpi_grid.py
+│       │       ├── links_card.py
+│       │       ├── metric_card.py
+│       │       ├── status_card.py
+│       │       └── table_card.py
+│       │
+│       ├── cli/
+│       │   ├── doctor.py
+│       │   ├── main.py
+│       │   └── web.py
+│       │
+│       ├── config_ui/
+│       │   ├── apply.py
+│       │   ├── audit.py
+│       │   ├── preview.py
+│       │   ├── read_model.py
+│       │   └── routes.py
+│       │
+│       ├── core/
+│       │   ├── ids.py
+│       │   ├── json.py
+│       │   ├── logging.py
+│       │   ├── paths.py
+│       │   └── security.py
+│       │
+│       ├── data/
+│       │   ├── envelopes.py
+│       │   ├── resolver.py
+│       │   ├── selectors.py
+│       │   └── sources.py
+│       │
+│       ├── pages/
+│       │   ├── models.py
+│       │   ├── registry.py
+│       │   ├── renderer.py
+│       │   └── router.py
+│       │
+│       ├── web/
+│       │   ├── __init__.py
+│       │   ├── app.py
+│       │   ├── templates/
+│       │   │   ├── base.html
+│       │   │   └── page.html
+│       │   └── static/
+│       │       ├── css/
+│       │       │   └── beeui.css
+│       │       └── js/
+│       │           └── beeui.js
+│       │
+│       └── theme/
+│           ├── css.py
+│           ├── models.py
+│           └── service.py
+│
+├── tests/
+│   ├── test_adapters.py
+│   ├── test_app.py
+│   ├── test_artifacts.py
+│   ├── test_blocks.py
+│   ├── test_config.py
+│   ├── test_pages.py
+│   ├── test_security.py
+│   └── test_smoke.py
+│
+├── pyproject.toml
+├── README.ru.md
+├── start.sh
+└── uv.lock
+```
+
+## Архитектура
+
+### 1. App/Web layer
+
+Отвечает за:
+
+- FastAPI app factory;
+- templates/static;
+- routes;
+- global layout;
+- API routes;
+- error pages.
+
+Ключевые модули:
+
+```text
+src/beeui_module/web/app.py
+src/beeui_module/web/templates/
+src/beeui_module/web/static/
+```
+
+Planned after Iteration 2:
+
+```text
+src/beeui_module/server.py
+src/beeui_module/pages/
+```
+
+### 2. Adapter layer
+
+Отвечает за подключение к продуктам.
+
+```text
+src/beeui_module/adapters/
+```
+
+Типы adapters:
+
+- `ProductUiAdapter` — base contract;
+- `BeeCapUiAdapter` — BeeCap-specific read-model adapter;
+- `BeeAgentUiAdapter` — BeeAgent-specific read-model adapter;
+- `HttpProductAdapter` — будущий standalone mode;
+- `FilesystemAdapter` — demo/local artifact reading.
+
+### 3. Data resolver layer
+
+Отвечает за:
+
+- source lookup;
+- selector resolution;
+- partial data;
+- warnings/errors;
+- normalized envelopes.
+
+```text
+src/beeui_module/data/
+```
+
+### 4. Blocks layer
+
+Отвечает за reusable UI blocks.
+
+```text
+src/beeui_module/blocks/
+src/beeui_module/web/templates/components/
+```
+
+### 5. Artifact layer
+
+Отвечает за safe artifact navigation.
+
+```text
+src/beeui_module/artifacts/
+```
+
+Security responsibilities:
+
+- artifact allowlist;
+- safe IDs;
+- path traversal guard;
+- JSON/JSONL tolerant parsing;
+- redaction;
+- no mutation.
+
+### 6. Config UI layer
+
+Отвечает за:
+
+- config read-model;
+- preview;
+- apply;
+- audit;
+- backup.
+
+```text
+src/beeui_module/config_ui/
+```
+
+Важно:
+
+- product config remains source of truth;
+- product validation callback is mandatory for apply;
+- BeeUI does not invent config semantics.
+
+### 7. Auth layer
+
+Planned layer.
+
+```text
+src/beeui_module/auth/
+```
+
+Отвечает за:
+
+- users;
+- sessions;
+- roles;
+- permissions;
+- CSRF;
+- route protection.
+
+## JSON API contract
+
+BeeUI API должен использовать единый envelope.
+Resolver envelope is an internal block data-resolution contract in Iteration 7.
+It is not yet a public `/api/*` route contract.
+Public BeeUI JSON API запланирован для следующих итераций.
+
+### Success
+
+```json
+{
+  "ok": true,
+  "status": "ok",
+  "data": {},
+  "warnings": [],
+  "meta": {
+    "source": "adapter",
+    "product": "beecap"
+  }
+}
+```
+
+### Partial
+
+```json
+{
+  "ok": true,
+  "status": "partial",
+  "data": {},
+  "warnings": [
+    {
+      "code": "artifact_missing",
+      "message": "health.json is missing"
+    }
+  ],
+  "meta": {
+    "source": "adapter",
+    "product": "beecap"
+  }
+}
+```
+
+### Error
+
+```json
+{
+  "ok": false,
+  "status": "error",
+  "error": {
+    "code": "invalid_run_id",
+    "message": "Invalid run_id"
+  },
+  "warnings": [],
+  "meta": {
+    "source": "beeui"
+  }
+}
+```
+
+## Planned routes
+
+### HTML
+
+```text
+GET /
+GET /runs
+GET /runs/{run_id}
+GET /runs/{run_id}/artifacts
+GET /config
+GET /admin
+GET /login
+GET /logout
+```
+
+### API
+
+```text
+GET /api/dashboard
+GET /api/runs
+GET /api/runs/{run_id}
+GET /api/runs/{run_id}/artifacts
+GET /api/runs/{run_id}/artifacts/{artifact_id}
+GET /api/config/read-model
+POST /api/config/preview
+POST /api/config/apply
+GET /api/actions
+POST /api/actions/{action_id}
+```
+
+Routes can be mounted under prefix:
+
+```text
+/ui
+/console
+/admin
+```
+
+depending on product integration.
+
+## Безопасность
+
+BeeUI находится на trust boundary, потому что отображает:
+
+- configs;
+- artifacts;
+- operator actions;
+- diagnostics;
+- product state;
+- potential admin controls.
+
+Правила безопасности:
+
+- read-only by default;
+- all IDs are untrusted input;
+- path traversal guard everywhere;
+- HTML autoescape enabled;
+- no arbitrary HTML/JS blocks;
+- artifact access allowlisted;
+- config write allowlisted;
+- action execution product-owned;
+- secrets redacted in HTML/API/logs/audits;
+- POST routes protected by CSRF when auth enabled;
+- no direct broker/runtime authority;
+- no hidden fallback from denied action to allowed action;
+- no automatic runtime restart after config apply.
+
+Особо запрещено:
+
+- отдавать `.env`;
+- отдавать raw secret values;
+- читать arbitrary path из query param;
+- делать direct shell commands из UI;
+- делать live broker calls из BeeUI;
+- писать runtime artifacts без product-owned action callback.
+
+## MVP roadmap summary
+
+Критический путь к MVP:
+
+```text
+Iteration 0 — Project skeleton and startup contract
+Iteration 1 — Tabler web shell v0
+Iteration 2 — Declarative pages and navigation v0
+Iteration 3 — Local Tabler vendor/assets and layout parity v1
+Iteration 4 — Theme, layout and navigation schema v1
+Iteration 5 — Block registry and static dashboard blocks v1
+Iteration 7 — Data sources and resolver v0
+Iteration 8 — Product adapter contract v0
+Iteration 9 — BeeCap adapter MVP
+Iteration 10 — Embedded mount API v0
+Iteration 11 — Generic artifact browser v1
+Iteration 12 — BeeCap dashboard parity MVP
+Iteration 13 — Runs list and run overview MVP
+```
+
+MVP считается достигнутым, если:
+
+- `beeui` запускается отдельно как demo;
+- `beeui` подключается к `beecap`;
+- BeeCap dashboard рендерится через BeeUI;
+- BeeCap current custom templates больше не расширяются вручную;
+- run list / run detail / artifact links работают;
+- UI read-only по умолчанию;
+- tests green.
+
+## Что должно остаться в BeeCap/BeeAgent после внедрения BeeUI
+
+Bee-продукты сохраняют:
+
+- core runtime;
+- config validation;
+- product artifacts;
+- product read-model;
+- domain-specific summaries;
+- bounded actions;
+- authority/security checks.
+
+Bee-продукты больше не должны дублировать:
+
+- base web shell;
+- Tabler layout;
+- sidebar/navbar;
+- reusable KPI cards;
+- generic tables;
+- generic artifact browser;
+- theme layer;
+- common config UI;
+- common admin/support pages.
+
+## Диагностика и тесты
+
+### Диагностика
+
+| Команда              | Что делает                                                  |
+| -------------------- | ----------------------------------------------------------- |
+| `./start.sh doctor`  | Проверка окружения, структуры, imports, config availability |
+| `./start.sh web`     | Запуск demo BeeUI web app                                   |
+| `./start.sh routes`  | Показ registered routes                                     |
+| `./start.sh version` | Показ версии BeeUI                                          |
+
+### Тесты
+
+```bash
+uv run pytest -q
+```
+
+### Web smoke
+
+```bash
+./start.sh web --host 127.0.0.1 --port 8780
+```
+
+Проверить:
+
+```text
+http://127.0.0.1:8780/
+http://127.0.0.1:8780/health
+```
+
+### Security smoke
+
+Проверить:
+
+- no secrets in HTML;
+- no secrets in API;
+- invalid run_id rejected;
+- path traversal rejected;
+- POST routes do not work without explicit implementation;
+- static files limited to BeeUI static directory.
+
+## Deployment
+
+### MVP deployment
+
+Embedded per product.
+
+```text
+container: beecap
+  includes beeui dependency
+  exposes beecap web
+
+container: beeagent
+  includes beeui dependency
+  exposes beeagent web
+```
+
+Плюсы:
+
+- проще;
+- меньше сетевых связей;
+- быстрее MVP;
+- меньше auth/CORS проблем.
+
+### Будущий deployment
+
+Standalone BeeUI.
+
+```text
+container: beeui
+container: beecap-api
+container: beeagent-api
+```
+
+Использовать только после стабилизации:
+
+- BeeUI API contracts;
+- product APIs;
+- auth/session model;
+- deployment model.
+
+## Важно
+
+BeeUI — это не просто UI kit.
+
+Правильное определение:
+
+```text
+BeeUI is a reusable UI/runtime framework for Bee products.
+```
+
+Он должен развиваться от простого embedded UI package к platform layer:
+
+1. server-rendered operator console;
+2. reusable dashboard blocks;
+3. artifact/config/admin views;
+4. stable JSON API;
+5. auth/RBAC;
+6. bounded operator controls;
+7. будущий no-code dashboard builder;
+8. будущий standalone frontend backend.
+
+Неправильное направление:
+
+```text
+Сразу делать no-code Retool/Webflow clone.
+```
+
+Это приведёт к месячной разработке без MVP.
+
+Правильное направление:
+
+```text
+Declarative schema first.
+Visual builder later.
+```
+
+## Текущий статус
+
+Проект создан как отдельная repo:
+
+```text
+~/Projects/beeui
+```
+
+Текущий статус:
+
+```text
+Iteration 11 — Generic artifact browser v1 — DONE
+```
+
+Работает:
+
+```bash
+./start.sh doctor
+./start.sh routes
+uv run pytest -q
+./start.sh web --host 127.0.0.1 --port 8780
+```
+
+- `/` рендерит literal и resolver-backed dashboard blocks from schema;
+- `/runs` рендерит empty state для страницы без block placements;
+- `/components*` рендерит internal read-only catalog of controlled primitives;
+- resolver-backed blocks читают значения из controlled read-only `demo` / `static` sources;
+- missing selector data рендерит degraded/error block state вместо падения страницы;
+- generic `ProductUiAdapter` contract доступен в `src/beeui_module/adapters/`;
+- optional adapter write/action methods недоступны по умолчанию;
+- `BeeCapFixtureAdapter` валидирует BeeCap-shaped fixture payloads;
+- BeeCap-like fixtures покрывают dashboard, runs, artifact references, partial и corrupted artifact states;
+- integration boundary задокументирован в `docs/INTEGRATION.md`;
+- `create_beeui_app(...)` accepts `config_path`, product metadata and adapter;
+- `mount_beeui(...)` mounts BeeUI into parent FastAPI app;
+- adapter is validated and stored in `app.state.beeui_adapter`;
+- product metadata is stored in `app.state.beeui_product`;
+- artifact browser HTML/API routes работают через adapter;
+- `/api/runs/{run_id}/artifacts*` routes доступны при `features.browser_artifact: true`;
+- adapter-backed dashboard/runs rendering остаётся future scope.