@retailcrm/embed-ui 0.9.21 → 0.9.22-alpha.1

package/CHANGELOG.md

@@ -1,6 +1,27 @@
 # Changelog
 
 
+## [0.9.22-alpha.1](https://github.com/retailcrm/embed-ui/compare/v0.9.21...v0.9.22-alpha.1) (2026-05-18)
+
+### Features
+
+* Embed UI init interactive mode added ([76d04fc](https://github.com/retailcrm/embed-ui/commit/76d04fc29755e03fd3ea56c2a5b495c854d8024f))
+* Embed UI initialization CLI added ([2770cfd](https://github.com/retailcrm/embed-ui/commit/2770cfde193b3816b20bd19705bf8c86bfcb20f4))
+* Embed UI project initialization added ([b6ec6ba](https://github.com/retailcrm/embed-ui/commit/b6ec6bae6cde10f8720b64568133f396b199ea67))
+* Endpoint target metadata generation added ([b52632d](https://github.com/retailcrm/embed-ui/commit/b52632d311b22ccc42199e99d5e543e7473e0050))
+* Init preflight diagnostics expanded ([771485a](https://github.com/retailcrm/embed-ui/commit/771485a8b52fad233162745bc257e7bee6fae982))
+* **v1-components:** UiLogicTree component was added ([63d46b9](https://github.com/retailcrm/embed-ui/commit/63d46b990339e00377c1d862b9831c8c7f86282b))
+* **v1-components:** UiPopconfirm component was added ([0999220](https://github.com/retailcrm/embed-ui/commit/09992203cd300c363419d4321aca8ba3ff91d261))
+* **v1-endpoint:** MCP project config initialization added ([a79082b](https://github.com/retailcrm/embed-ui/commit/a79082b963abf66e5dd2dd4246c6a1323d6da7c6))
+* **v1-endpoint:** MCP target resources and agent setup added ([8d7b620](https://github.com/retailcrm/embed-ui/commit/8d7b62026500b328fc3d199dbefb9e52c907924a))
+
+### Bug Fixes
+
+* Generated init project lint issues corrected ([d7d80f2](https://github.com/retailcrm/embed-ui/commit/d7d80f29264b57b71bcf7354ee0aa10c5335113e))
+* resolved embed-ui agents docs path ([7117caf](https://github.com/retailcrm/embed-ui/commit/7117caf92b0efc8c9ee43176162da36e5d47f21c))
+* **v1-components:** Storybook serve allowed hosts were updated ([259f493](https://github.com/retailcrm/embed-ui/commit/259f49315ae5388fd74da3c4faf0fef5d099b5bc))
+* Vue remote peer dependency ownership corrected ([cebeaa0](https://github.com/retailcrm/embed-ui/commit/cebeaa00d725035e69381e5cd9a1013b4b8db914))
+* Vue remote runtime dependency restored ([0ec71e0](https://github.com/retailcrm/embed-ui/commit/0ec71e0991451bbad9b3fa8f545ff5e5d97b691a))
 ## [0.9.21](https://github.com/retailcrm/embed-ui/compare/v0.9.20...v0.9.21) (2026-04-30)
 
 ### Bug Fixes

package/README.md

@@ -10,7 +10,7 @@ API и компоненты для создания расширений инт
 
 - `v1-components` — UI-компоненты и сопутствующая документация, [README.md пакета](./packages/v1-components/README.md).
 - `v1-contexts` — реактивные контексты и доступ к данным RetailCRM JS API, [README.md пакета](./packages/v1-contexts/README.md).
-- `v1-endpoint` — endpoint API для remote-страниц и виджетов, [README.md пакета](./packages/v1-endpoint/README.md).
+- `v1-endpoint` — endpoint API для встраиваемых страниц и виджетов, [README.md пакета](./packages/v1-endpoint/README.md).
 - `v1-testing` — тестовые утилиты и вспомогательные типы для интеграций, [README.md пакета](./packages/v1-testing/README.md).
 - `v1-types` — базовые type declarations для публичного API, [README.md пакета](./packages/v1-types/README.md).
 
@@ -21,7 +21,102 @@ API и компоненты для создания расширений инт
 npx @retailcrm/embed-ui-v1-components init-agents
 ```
 
-## Обновление версий в целевом проекте
+## CLI `@retailcrm/embed-ui`
+
+Пакет поставляет бинарник `embed-ui`, который можно запускать через `npx`.
+CLI умеет обновлять версии пакетов, добавлять пакеты в существующий проект и выполнять начальную инициализацию
+фронтенда расширения.
+
+```bash
+npx @retailcrm/embed-ui --help
+```
+
+### Начальная Инициализация
+
+Команда `init` создает или дополняет проект фронтенда расширения:
+
+- добавляет `package.json`, если его еще нет;
+- добавляет зависимости `@retailcrm/embed-ui*`, `vue`, `pinia`, `vue-i18n` и dev-зависимости для Vite, TypeScript и ESLint;
+- создает `tsconfig.json`, `vite.config.ts`, `eslint.config.js`, `env.d.ts`;
+- создает стартовые файлы во frontend-каталоге: endpoint worker, страницу настроек, виджет заказа, i18n JSON-сообщения;
+- добавляет `extensionrc.json` и `scripts/publish-extension.mjs`;
+- добавляет `AGENTS.md` и MCP-настройки пакетов, если они не отключены флагами.
+
+```bash
+npx @retailcrm/embed-ui init ./web --package-manager yarn
+```
+
+Если не указывать дополнительные флаги, `init` работает так:
+
+- корень проекта — текущий рабочий каталог;
+- frontend-каталог — позиционный аргумент команды, а если его нет, то `./src` для нового проекта или `./web`, если `./src` уже существует;
+- версия пакетов — последняя опубликованная версия из npm;
+- package manager — определяется по единственному lock-файлу в корне проекта, в интерактивном терминале запрашивается у пользователя, в неинтерактивном режиме используется `npm`;
+- пакеты — `@retailcrm/embed-ui`, `v1-components`, `v1-contexts`, `v1-types` и `v1-endpoint`;
+- установка зависимостей — запускается автоматически после изменения `package.json`;
+- шаблон — создается стартовая конфигурация для страницы настроек и виджета `order/card:common.after`;
+- каталоги — создаются `endpoint`, `pages`, `widgets`, `shared`, `i18n` и `i18n/locales` внутри frontend-каталога;
+- `AGENTS.md` — создается или дополняется инструкциями корневого пакета и выбранных пакетов;
+- MCP — добавляется `.mcp.json` для `v1-endpoint`;
+- client configs для Cursor, Junie и VS Code — не создаются без `--mcp-client-configs`;
+- существующие файлы не перезаписываются, а зависимости с потенциальным конфликтом не заменяются без явных force-флагов.
+
+По умолчанию команда использует текущий рабочий каталог как корень проекта. Его можно задать явно:
+
+```bash
+npx @retailcrm/embed-ui init ./web --cwd ./my-project --package-manager npm
+```
+
+Если в проекте уже есть `src`, для нового фронтенда расширения удобнее использовать отдельный каталог, например
+`./web`. CLI не перезаписывает существующие файлы без явного разрешения и выводит предупреждения о пропущенных шагах.
+
+Полезные флаги:
+
+- `--no-install` — не запускать установку зависимостей после изменения `package.json`.
+- `--interactive` — задать основные параметры через вопросы в TTY, сохранив флаги как явные ограничения.
+- `--version 0.9.21` — использовать указанную версию пакетов вместо последней версии из npm.
+- `--exact` — записывать точные версии вместо диапазонов.
+- `--packages embed-ui,components,contexts,types,endpoint` — явно выбрать пакеты для установки и настройки.
+- `--force-deps` — заменить несовместимые версии зависимостей.
+- `--fix-sections` — перенести зависимости в ожидаемые секции `dependencies`/`devDependencies`.
+- `--force-files` — перезаписать генерируемые стартовые файлы.
+- `--no-configs` — не создавать `tsconfig.json`, `vite.config.ts`, `eslint.config.js` и `env.d.ts`.
+- `--no-template` — не создавать стартовые Vue-файлы и `extensionrc.json`.
+- `--no-agents` — не создавать и не дополнять `AGENTS.md`.
+- `--no-mcp` — не добавлять MCP-настройки пакетов.
+- `--mcp-client-configs cursor,junie,vscode` — дополнительно создать project-level конфиги поддерживаемых AI-клиентов.
+
+`--force` включает силовой режим для управляемых частей, но учитывает флаги `--no-*`. Например, можно обновить только
+агентские инструкции и MCP-настройки без перегенерации стартовых файлов:
+
+```bash
+npx @retailcrm/embed-ui init ./web --force --no-install --no-template
+```
+
+### AGENTS.md И MCP
+
+При `init` CLI добавляет общий раздел в `AGENTS.md`, а пакеты могут добавить свои инструкции. Сейчас это используют:
+
+- `@retailcrm/embed-ui-v1-components` — добавляет порядок чтения README, AI-документации и YAML-профилей компонентов.
+- `@retailcrm/embed-ui-v1-endpoint` — добавляет инструкции по целям виджетов и MCP-ресурсам.
+
+Для `v1-endpoint` также создается `.mcp.json` с сервером `retailcrm-embed-ui-v1-endpoint`. Он отдает AI-friendly
+описания целей виджетов через ресурсы:
+
+- `embed-ui-v1-endpoint://targets`;
+- `embed-ui-v1-endpoint://targets/<encoded-target>`.
+
+Конфиги конкретных клиентов не создаются по умолчанию, потому что в них чаще бывают пользовательские правки.
+Чтобы добавить только поддерживаемые project-level конфиги, укажите:
+
+```bash
+npx @retailcrm/embed-ui init ./web --no-install --mcp-client-configs cursor,junie,vscode
+```
+
+Повторный запуск без `--force` не дублирует управляемые секции и записи MCP. При `--force` обновляются только записи
+этого пакета, ручные серверы и соседние разделы не удаляются.
+
+### Обновление Версий
 
 Можно запустить бинарник через `npx`, чтобы обновить пакеты `@retailcrm/embed-ui*` во всех `package.json`
 текущего рабочего дерева или выбранного поддерева
@@ -37,6 +132,8 @@ npx @retailcrm/embed-ui --target ./my-project --dry-run
 По умолчанию используется последняя версия из npm. Флаг `--exact` переключает формат обновления на точную версию.
 CLI сохраняет исходные отступы и переводы строк в каждом изменяемом `package.json`.
 
+### Добавление Пакетов
+
 Для точечного добавления пакетов только в один `package.json` есть флаг `--add`.
 Если не передать `--packages`, CLI откроет интерактивный режим с выбором пакетов и кратким описанием.
 
@@ -46,6 +143,9 @@ npx @retailcrm/embed-ui --add --packages components,contexts
 npx @retailcrm/embed-ui --add --target ./my-project --version 0.9.11
 ```
 
+Доступные идентификаторы пакетов: `embed-ui`, `components`, `contexts`, `types`, `endpoint`.
+Пакет `testing` пока не добавляется через публичную инициализацию.
+
 ## Цели встраивания
 
 Цели встраивания определяют места, где будет размещена разметка виджета, генерируемая расширением.