diff --git a/skills/commit-workflow/SKILL.md b/.agents/skills/commit-workflow/SKILL.md similarity index 100% rename from skills/commit-workflow/SKILL.md rename to .agents/skills/commit-workflow/SKILL.md diff --git a/skills/local-ci-simulation/SKILL.md b/.agents/skills/local-ci-simulation/SKILL.md similarity index 100% rename from skills/local-ci-simulation/SKILL.md rename to .agents/skills/local-ci-simulation/SKILL.md diff --git a/skills/local-ci-simulation/agents/openai.yaml b/.agents/skills/local-ci-simulation/agents/openai.yaml similarity index 100% rename from skills/local-ci-simulation/agents/openai.yaml rename to .agents/skills/local-ci-simulation/agents/openai.yaml diff --git a/skills/sync-remote-host-registry/SKILL.md b/.agents/skills/sync-remote-host-registry/SKILL.md similarity index 100% rename from skills/sync-remote-host-registry/SKILL.md rename to .agents/skills/sync-remote-host-registry/SKILL.md diff --git a/skills/yarn-lock-conflict-resolution/SKILL.md b/.agents/skills/yarn-lock-conflict-resolution/SKILL.md similarity index 100% rename from skills/yarn-lock-conflict-resolution/SKILL.md rename to .agents/skills/yarn-lock-conflict-resolution/SKILL.md diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 63bd5037..c2201962 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -36,6 +36,9 @@ jobs: - name: Build worktree run: yarn workspaces foreach -A --topological-dev run build + - name: Ensure root bin is generated + run: test -s bin/embed-ui.mjs + - name: Run eslint run: yarn eslint diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 360c88c1..9f0380c4 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -41,6 +41,9 @@ jobs: - name: Build worktree run: yarn workspaces foreach -A --topological-dev run build + - name: Ensure root bin is generated + run: test -s bin/embed-ui.mjs + - name: Run eslint run: yarn eslint @@ -67,6 +70,9 @@ jobs: - name: Build worktree run: yarn workspaces foreach -A --topological-dev run build + - name: Ensure root bin is generated + run: test -s bin/embed-ui.mjs + - name: Run tests run: yarn test diff --git a/.gitignore b/.gitignore index 355e15f6..ee13811c 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,8 @@ generated node_modules coverage artifacts/ +/bin/ +packages/v1-endpoint/docs/targets/ .codex .npmrc diff --git a/.npmignore b/.npmignore index 5db7c059..b22d3580 100644 --- a/.npmignore +++ b/.npmignore @@ -23,6 +23,7 @@ eslint.config.js tsconfig.json tsconfig.test.json vite.config.ts +vite.config.bin.ts vitest.config.ts yarn.lock diff --git a/AGENTS.md b/AGENTS.md index 1180a22f..27cf448d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -93,15 +93,16 @@ yarn workspace @retailcrm/embed-ui-v1-components run storybook:build ``` ## Commit Workflow -- Before creating commits, you must read `skills/commit-workflow/SKILL.md` and follow its rules. +- Before creating commits, you must read `.agents/skills/commit-workflow/SKILL.md` and follow its rules. ## Skills -- Repository-local skills are available under `skills/`. +- Repository-local skills are available under `.agents/skills/`. - If a skill conflicts with this file, follow `AGENTS.md`. - Current local skills: - - `skills/commit-workflow/SKILL.md` - - `skills/sync-remote-host-registry/SKILL.md` - - `skills/yarn-lock-conflict-resolution/SKILL.md` + - `.agents/skills/commit-workflow/SKILL.md` + - `.agents/skills/local-ci-simulation/SKILL.md` + - `.agents/skills/sync-remote-host-registry/SKILL.md` + - `.agents/skills/yarn-lock-conflict-resolution/SKILL.md` ## Notes - Do not assume legacy rules from other repositories (especially `omnica`) apply here. diff --git a/README.md b/README.md index 59a2441f..c241a3a7 100644 --- a/README.md +++ b/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,100 @@ 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`. +- `--version 0.9.21` — использовать указанную версию пакетов вместо последней версии из npm. +- `--exact` — записывать точные версии вместо диапазонов. +- `--packages embed-ui,components,contexts,types,endpoint` — явно выбрать пакеты для установки и настройки. +- `--force-deps` — заменить несовместимые версии зависимостей. +- `--fix-sections` — перенести зависимости в ожидаемые секции `dependencies`/`devDependencies`. +- `--force-files` — перезаписать генерируемые стартовые файлы. +- `--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/`. + +Конфиги конкретных клиентов не создаются по умолчанию, потому что в них чаще бывают пользовательские правки. +Чтобы добавить только поддерживаемые 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 +130,8 @@ npx @retailcrm/embed-ui --target ./my-project --dry-run По умолчанию используется последняя версия из npm. Флаг `--exact` переключает формат обновления на точную версию. CLI сохраняет исходные отступы и переводы строк в каждом изменяемом `package.json`. +### Добавление Пакетов + Для точечного добавления пакетов только в один `package.json` есть флаг `--add`. Если не передать `--packages`, CLI откроет интерактивный режим с выбором пакетов и кратким описанием. @@ -46,6 +141,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` пока не добавляется через публичную инициализацию. + ## Цели встраивания Цели встраивания определяют места, где будет размещена разметка виджета, генерируемая расширением. diff --git a/bin/embed-ui-update.mjs b/bin/embed-ui-update.mjs deleted file mode 100755 index 20469ed9..00000000 --- a/bin/embed-ui-update.mjs +++ /dev/null @@ -1,617 +0,0 @@ -#!/usr/bin/env node - -import { createInterface } from 'node:readline/promises' -import { execFileSync } from 'node:child_process' -import fs from 'node:fs' -import path from 'node:path' -import { pathToFileURL } from 'node:url' -import process from 'node:process' - -export const ROOT_PACKAGE = '@retailcrm/embed-ui' -export const TARGET_SECTIONS = [ - 'dependencies', - 'devDependencies', - 'peerDependencies', - 'optionalDependencies', -] - -export const INSTALLABLE_PACKAGES = [ - { - id: 'embed-ui', - name: ROOT_PACKAGE, - section: 'dependencies', - description: 'Базовый пакет с общим API и согласованными v1-зависимостями.', - }, - { - id: 'components', - name: '@retailcrm/embed-ui-v1-components', - section: 'dependencies', - description: 'UI-компоненты для host/remote приложений.', - }, - { - id: 'contexts', - name: '@retailcrm/embed-ui-v1-contexts', - section: 'dependencies', - description: 'Реактивные контексты RetailCRM JS API.', - }, - { - id: 'types', - name: '@retailcrm/embed-ui-v1-types', - section: 'dependencies', - description: 'Базовые type declarations для RetailCRM JS API.', - }, - { - id: 'testing', - name: '@retailcrm/embed-ui-v1-testing', - section: 'devDependencies', - description: 'Вспомогательные утилиты и типы для тестов интеграций.', - }, - { - id: 'endpoint', - name: '@retailcrm/embed-ui-v1-endpoint', - section: 'dependencies', - description: 'Endpoint API для интеграций в RetailCRM.', - }, -] - -const DEFAULT_INDENT = ' ' -const DEFAULT_NEWLINE = '\n' -const SKIP_DIRECTORIES = new Set([ - '.git', - '.hg', - '.svn', - '.yarn', - 'node_modules', - 'dist', - 'build', - 'coverage', -]) - -const HELP_TEXT = `Usage: - npx @retailcrm/embed-ui [target] [version] [options] - -Options: - -t, --target Target path (default: current directory) - -v, --version Target version. If omitted, latest npm version is used - --exact Use exact version instead of range - --dry-run Show changes without writing package.json - --add Add selected embed-ui packages into one package.json - --packages Comma-separated package ids or names for --add - -h, --help Show this help - -Examples: - npx @retailcrm/embed-ui - npx @retailcrm/embed-ui --version 0.9.11 - npx @retailcrm/embed-ui ./my-project 0.9.11 - npx @retailcrm/embed-ui --target ./my-project --dry-run - npx @retailcrm/embed-ui --add - npx @retailcrm/embed-ui --add --packages components,contexts -` - -const isSemverLike = (value) => /^v?\d+\.\d+\.\d+/.test(value) -const stripLeadingV = (value) => value.replace(/^v/, '') - -const parsePackageList = (value) => - value - .split(',') - .map((entry) => entry.trim()) - .filter(Boolean) - -export const parseArgs = (argv) => { - const options = { - target: process.cwd(), - version: null, - dryRun: false, - exact: false, - add: false, - packages: null, - } - - const positionals = [] - - for (let index = 0; index < argv.length; index++) { - const argument = argv[index] - - if (argument === '-h' || argument === '--help') { - console.log(HELP_TEXT) - process.exit(0) - } - - if (argument === '-t' || argument === '--target') { - const value = argv[index + 1] - if (!value) { - throw new Error('Option --target requires a value') - } - - options.target = path.resolve(process.cwd(), value) - index++ - continue - } - - if (argument === '-v' || argument === '--version') { - const value = argv[index + 1] - if (!value) { - throw new Error('Option --version requires a value') - } - - options.version = stripLeadingV(value) - index++ - continue - } - - if (argument === '--packages') { - const value = argv[index + 1] - if (!value) { - throw new Error('Option --packages requires a value') - } - - options.packages = parsePackageList(value) - index++ - continue - } - - if (argument === '--dry-run') { - options.dryRun = true - continue - } - - if (argument === '--exact') { - options.exact = true - continue - } - - if (argument === '--add') { - options.add = true - continue - } - - if (argument.startsWith('-')) { - throw new Error(`Unknown option: ${argument}`) - } - - positionals.push(argument) - } - - if (positionals.length > 2) { - throw new Error('Too many positional arguments') - } - - if (positionals.length >= 1) { - const first = positionals[0] - if (!options.version && isSemverLike(first)) { - options.version = stripLeadingV(first) - } else { - options.target = path.resolve(process.cwd(), first) - } - } - - if (positionals.length === 2) { - if (options.version) { - throw new Error('Version is already specified') - } - - options.version = stripLeadingV(positionals[1]) - } - - if (options.packages && !options.add) { - throw new Error('Option --packages can only be used together with --add') - } - - return options -} - -export const resolveLatestVersion = () => { - const output = execFileSync( - 'npm', - ['view', ROOT_PACKAGE, 'version'], - { - encoding: 'utf8', - stdio: ['ignore', 'pipe', 'pipe'], - } - ).trim() - - if (!output) { - throw new Error(`Cannot resolve latest version for ${ROOT_PACKAGE}`) - } - - return output -} - -export const isTargetPackage = (name) => - name === ROOT_PACKAGE || name.startsWith(`${ROOT_PACKAGE}-`) - -const createRange = (version, exact) => exact ? version : `^${version}` - -export const formatRange = (currentRange, nextVersion, exact) => { - if (exact) { - return nextVersion - } - - if (currentRange.startsWith('workspace:')) { - return currentRange - } - - if (currentRange.startsWith('~')) { - return `~${nextVersion}` - } - - if (currentRange.startsWith('^')) { - return `^${nextVersion}` - } - - return `^${nextVersion}` -} - -export const detectFormatting = (source) => { - const newline = source.includes('\r\n') ? '\r\n' : DEFAULT_NEWLINE - const indentMatch = source.match(/\n([ \t]+)"/) - - return { - indent: indentMatch?.[1] ?? DEFAULT_INDENT, - newline, - trailingNewline: source.endsWith('\n') || source.endsWith('\r\n'), - } -} - -export const serializePackageJson = (packageJson, formatting) => { - const serialized = JSON.stringify(packageJson, null, formatting.indent) - .replace(/\n/g, formatting.newline) - - return formatting.trailingNewline - ? `${serialized}${formatting.newline}` - : serialized -} - -const ensureDirectoryExists = (targetPath) => { - if (!fs.existsSync(targetPath)) { - throw new Error(`Path not found: ${targetPath}`) - } - - const stat = fs.statSync(targetPath) - if (!stat.isDirectory()) { - throw new Error(`Target is not a directory: ${targetPath}`) - } -} - -export const resolvePackageJsonPath = (targetPath) => { - if (path.basename(targetPath) === 'package.json') { - if (!fs.existsSync(targetPath)) { - throw new Error(`package.json not found: ${targetPath}`) - } - - return targetPath - } - - const packageJsonPath = path.resolve(targetPath, 'package.json') - - if (!fs.existsSync(packageJsonPath)) { - throw new Error(`package.json not found: ${packageJsonPath}`) - } - - return packageJsonPath -} - -export const collectPackageJsonPaths = (targetPath) => { - const resolvedTarget = path.resolve(targetPath) - - if (!fs.existsSync(resolvedTarget)) { - throw new Error(`Path not found: ${resolvedTarget}`) - } - - if (path.basename(resolvedTarget) === 'package.json') { - return [resolvedTarget] - } - - ensureDirectoryExists(resolvedTarget) - - const packageJsonPaths = [] - - const visit = (directoryPath) => { - const packageJsonPath = path.join(directoryPath, 'package.json') - if (fs.existsSync(packageJsonPath) && fs.statSync(packageJsonPath).isFile()) { - packageJsonPaths.push(packageJsonPath) - } - - for (const entry of fs.readdirSync(directoryPath, { withFileTypes: true })) { - if (!entry.isDirectory() || entry.isSymbolicLink()) { - continue - } - - if (SKIP_DIRECTORIES.has(entry.name)) { - continue - } - - visit(path.join(directoryPath, entry.name)) - } - } - - visit(resolvedTarget) - - return packageJsonPaths.sort() -} - -const findDependencySection = (packageJson, packageName) => { - for (const section of TARGET_SECTIONS) { - const dependencyMap = packageJson[section] - - if (dependencyMap && typeof dependencyMap === 'object' && packageName in dependencyMap) { - return section - } - } - - return null -} - -export const updatePackageJson = (packageJson, version, exact) => { - const updates = [] - - for (const section of TARGET_SECTIONS) { - const dependencyMap = packageJson[section] - - if (!dependencyMap || typeof dependencyMap !== 'object') { - continue - } - - for (const [name, currentRange] of Object.entries(dependencyMap)) { - if (!isTargetPackage(name) || typeof currentRange !== 'string') { - continue - } - - const nextRange = formatRange(currentRange, version, exact) - if (nextRange === currentRange) { - continue - } - - dependencyMap[name] = nextRange - updates.push({ - type: 'update', - section, - name, - currentRange, - nextRange, - }) - } - } - - return updates -} - -export const resolveInstallPackages = (tokens) => { - const selectedPackages = [] - const seen = new Set() - - for (const token of tokens) { - const normalized = token.trim() - if (!normalized) { - continue - } - - const numericIndex = Number(normalized) - const selectedPackage = - Number.isInteger(numericIndex) && numericIndex >= 1 && numericIndex <= INSTALLABLE_PACKAGES.length - ? INSTALLABLE_PACKAGES[numericIndex - 1] - : INSTALLABLE_PACKAGES.find((entry) => entry.id === normalized || entry.name === normalized) - - if (!selectedPackage) { - const supported = INSTALLABLE_PACKAGES - .map((entry, index) => `${index + 1}/${entry.id}/${entry.name}`) - .join(', ') - - throw new Error(`Unknown add target "${normalized}". Supported values: ${supported}`) - } - - if (seen.has(selectedPackage.name)) { - continue - } - - seen.add(selectedPackage.name) - selectedPackages.push(selectedPackage) - } - - return selectedPackages -} - -export const installPackages = (packageJson, packages, version, exact) => { - const updates = [] - - for (const selectedPackage of packages) { - const section = findDependencySection(packageJson, selectedPackage.name) ?? selectedPackage.section - const dependencyMap = packageJson[section] ?? {} - - if (!(section in packageJson)) { - packageJson[section] = dependencyMap - } - - const currentRange = dependencyMap[selectedPackage.name] - const nextRange = typeof currentRange === 'string' - ? formatRange(currentRange, version, exact) - : createRange(version, exact) - - if (currentRange === nextRange) { - continue - } - - dependencyMap[selectedPackage.name] = nextRange - updates.push({ - type: typeof currentRange === 'string' ? 'update' : 'install', - section, - name: selectedPackage.name, - currentRange: typeof currentRange === 'string' ? currentRange : null, - nextRange, - }) - } - - return updates -} - -export const promptForInstallSelection = async (packageJson) => { - if (!process.stdin.isTTY || !process.stdout.isTTY) { - throw new Error('Interactive add mode requires a TTY. Use --packages to select packages explicitly.') - } - - console.log('Выберите пакеты для установки в текущий package.json:') - for (const [index, selectedPackage] of INSTALLABLE_PACKAGES.entries()) { - const currentSection = findDependencySection(packageJson, selectedPackage.name) - const installedHint = currentSection ? ` Уже есть в ${currentSection}.` : '' - - console.log(` ${index + 1}. ${selectedPackage.name} (${selectedPackage.id})`) - console.log(` ${selectedPackage.description} Раздел по умолчанию: ${selectedPackage.section}.${installedHint}`) - } - - const readline = createInterface({ - input: process.stdin, - output: process.stdout, - }) - - try { - while (true) { - const answer = await readline.question( - 'Введите номера, ids или имена пакетов через запятую (например: 1,3 или components,types): ' - ) - - const tokens = parsePackageList(answer) - if (tokens.length === 0) { - return [] - } - - try { - return resolveInstallPackages(tokens) - } catch (error) { - const message = error instanceof Error ? error.message : String(error) - console.error(message) - } - } - } finally { - readline.close() - } -} - -const readPackageJson = (packageJsonPath) => { - const source = fs.readFileSync(packageJsonPath, 'utf8') - - return { - formatting: detectFormatting(source), - packageJson: JSON.parse(source), - } -} - -const writePackageJson = (packageJsonPath, packageJson, formatting) => { - fs.writeFileSync(packageJsonPath, serializePackageJson(packageJson, formatting), 'utf8') -} - -const printChanges = (changes) => { - for (const change of changes) { - const prefix = change.type === 'install' - ? `${change.section}: ${change.name} -> ${change.nextRange}` - : `${change.section}: ${change.name} ${change.currentRange} -> ${change.nextRange}` - - console.log(` ${prefix}`) - } -} - -export const runUpdate = (options) => { - const version = options.version ?? resolveLatestVersion() - const packageJsonPaths = collectPackageJsonPaths(options.target) - const reports = [] - - for (const packageJsonPath of packageJsonPaths) { - const { formatting, packageJson } = readPackageJson(packageJsonPath) - const updates = updatePackageJson(packageJson, version, options.exact) - - if (updates.length === 0) { - continue - } - - if (!options.dryRun) { - writePackageJson(packageJsonPath, packageJson, formatting) - } - - reports.push({ packageJsonPath, updates }) - } - - if (reports.length === 0) { - console.log(`No ${ROOT_PACKAGE}* dependencies found or changed under ${path.resolve(options.target)}`) - return - } - - const totalUpdates = reports.reduce((sum, report) => sum + report.updates.length, 0) - - console.log(`Resolved version: ${version}`) - for (const report of reports) { - console.log(report.packageJsonPath) - printChanges(report.updates) - } - - if (options.dryRun) { - console.log('Dry run enabled, package.json files were not modified') - return - } - - console.log( - `Updated ${totalUpdates} dependency entries in ${reports.length} package.json file(s) under ${path.resolve(options.target)}` - ) -} - -export const runAdd = async (options) => { - const version = options.version ?? resolveLatestVersion() - const packageJsonPath = resolvePackageJsonPath(path.resolve(options.target)) - const { formatting, packageJson } = readPackageJson(packageJsonPath) - const selectedPackages = options.packages - ? resolveInstallPackages(options.packages) - : await promptForInstallSelection(packageJson) - - if (selectedPackages.length === 0) { - console.log('Nothing selected, package.json was not modified') - return - } - - const updates = installPackages(packageJson, selectedPackages, version, options.exact) - - if (updates.length === 0) { - console.log(`Selected packages are already installed with matching ranges in ${packageJsonPath}`) - return - } - - console.log(`Resolved version: ${version}`) - console.log(packageJsonPath) - printChanges(updates) - - if (options.dryRun) { - console.log('Dry run enabled, package.json was not modified') - return - } - - writePackageJson(packageJsonPath, packageJson, formatting) - console.log(`Installed ${updates.length} package entries in ${packageJsonPath}`) -} - -export const main = async (argv = process.argv.slice(2)) => { - const options = parseArgs(argv) - - if (options.add) { - await runAdd(options) - return - } - - runUpdate(options) -} - -const isExecutedDirectly = () => { - const entryPath = process.argv[1] - - if (!entryPath) { - return false - } - - return pathToFileURL(path.resolve(entryPath)).href === import.meta.url -} - -if (isExecutedDirectly()) { - try { - await main() - } catch (error) { - const message = error instanceof Error ? error.message : String(error) - console.error(message) - process.exit(1) - } -} diff --git a/eslint.config.js b/eslint.config.js index 43f2e950..8c0fbb39 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -172,5 +172,7 @@ export default defineConfig([ }, { ignores: ['dist/*'] }, { ignores: ['**/dist/*'] }, + { ignores: ['bin/embed-ui.mjs'] }, + { ignores: ['src/cmd/embed-ui/templates/**'] }, { ignores: ['packages/**/generated/**'] }, ]) diff --git a/meta/index.ts b/meta/index.ts index ba9dfb2e..1e07858f 100644 --- a/meta/index.ts +++ b/meta/index.ts @@ -1,608 +1,27 @@ -import type { SchemaListByTarget } from '~types/widget' import type { TranslationList } from '@retailcrm/embed-ui-v1-types/doc' -import type { UnionToArray } from '@retailcrm/embed-ui-v1-types/scaffolding' -import { keysOf } from '@/utilities' - -export const targetListDocumentation: { - [Target in keyof SchemaListByTarget]: { - description: TranslationList; - location: TranslationList; - contexts: UnionToArray; - customContexts: string[]; - actions: string[]; - } -} = { - 'customer/card:phone': { - description: { - 'en-GB': 'Widget for customer phone list item', - 'es-ES': 'Widget para el elemento de la lista de teléfonos del cliente', - 'ru-RU': 'Виджет для элемента списка телефонов клиента', - }, - location: { - 'en-GB': 'Right after the phone number in the list', - 'es-ES': 'Justo después del número de teléfono en la lista', - 'ru-RU': 'Сразу после номера телефона в списке', - }, - contexts: [ - 'customer/card', - 'customer/card:phone', - 'user/current', - 'settings', - ], - customContexts: ['customer'], - actions: [], - }, - 'customer/card:communications.after': { - description: { - 'en-GB': 'Widget for enhancing the communication section in the left column of the customer page.', - 'es-ES': 'Widget para ampliar la sección de comunicación en la columna izquierda de la página del cliente.', - 'ru-RU': 'Виджет для дополнения секции коммуникаций в левой колонке страницы клиента.', - }, - location: { - 'en-GB': 'Right below the short summary, in the communication section', - 'es-ES': 'Justo debajo del resumen breve, en la sección de comunicación', - 'ru-RU': 'Сразу под краткой сводкой, в секции коммуникаций', - }, - contexts: [ - 'customer/card', - 'user/current', - 'settings', - ], - customContexts: ['customer'], - actions: [], - }, - 'customer/card:inWork.before': { - description: { - 'en-GB': 'Widget for the contact request item', - 'es-ES': 'Widget para el elemento de solicitud de contacto', - 'ru-RU': 'Виджет для элемента обращений', - }, - location: { - 'en-GB': 'At the beginning of the "In Progress" block in the client card', - 'es-ES': 'Al principio del bloque "En progreso" en la tarjeta del cliente', - 'ru-RU': 'В начале блока "В работе" в карточке клиента', - }, - contexts: [ - 'customer/card', - 'user/current', - 'settings', - ], - customContexts: ['customer'], - actions: [], - }, - 'customer/card:inWork.after': { - description: { - 'en-GB': 'Widget for the contact request item', - 'es-ES': 'Widget para el elemento de solicitud de contacto', - 'ru-RU': 'Виджет для элемента обращений', - }, - location: { - 'en-GB': 'At the end of the "In progress" block in the client card', - 'es-ES': 'Al final del bloque "En progreso" en la tarjeta del cliente', - 'ru-RU': 'В конце блока "В работе" в карточке клиента', - }, - contexts: [ - 'customer/card', - 'user/current', - 'settings', - ], - customContexts: ['customer'], - actions: [], - }, - 'order/card:common.before': { - description: { - 'en-GB': 'Widget for the section with common data', - 'es-ES': 'Widget para la sección con datos comunes', - 'ru-RU': 'Виджет для секции с основными данными', - }, - location: { - 'en-GB': 'Section start, right above the input fields', - 'es-ES': 'Inicio de la sección, justo encima de los campos de entrada', - 'ru-RU': 'Начало секции, над полями ввода', - }, - contexts: [ - 'order/card', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/card:common.after': { - description: { - 'en-GB': 'Widget for the section with common data', - 'es-ES': 'Widget para la sección con datos comunes', - 'ru-RU': 'Виджет для секции с основными данными', - }, - location: { - 'en-GB': 'Section end, right under the input fields', - 'es-ES': 'Fin de la sección, justo debajo de los campos de entrada', - 'ru-RU': 'Конец секции, под полями ввода', - }, - contexts: [ - 'order/card', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/card:customer.before': { - description: { - 'en-GB': 'Widget for the section with customer data', - 'es-ES': 'Widget para la sección con datos del cliente', - 'ru-RU': 'Виджет для секции с данными клиента', - }, - location: { - 'en-GB': 'Section start, right above the input fields', - 'es-ES': 'Inicio de la sección, justo encima de los campos de entrada', - 'ru-RU': 'Начало секции, над полями ввода', - }, - contexts: [ - 'order/card', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/card:customer.after': { - description: { - 'en-GB': 'Widget for the section with customer data', - 'es-ES': 'Widget para la sección con datos del cliente', - 'ru-RU': 'Виджет для секции с данными клиента', - }, - location: { - 'en-GB': 'Section end, right under the input fields', - 'es-ES': 'Fin de la sección, justo debajo de los campos de entrada', - 'ru-RU': 'Конец секции, под полями ввода', - }, - contexts: [ - 'order/card', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/card:customer.email': { - description: { - 'en-GB': 'Widget for customer email input field', - 'es-ES': 'Widget para el campo de entrada del correo electrónico del cliente', - 'ru-RU': 'Виджет для поля ввода email клиента', - }, - location: { - 'en-GB': 'Right after the input field', - 'es-ES': 'Justo después del campo de entrada', - 'ru-RU': 'Сразу после поля ввода', - }, - contexts: [ - 'order/card', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/card:customer.phone': { - description: { - 'en-GB': 'Widget for customer phone input field', - 'es-ES': 'Widget para el campo de entrada del teléfono del cliente', - 'ru-RU': 'Виджет для поля ввода телефона клиента', - }, - location: { - 'en-GB': 'Right after the input field', - 'es-ES': 'Justo después del campo de entrada', - 'ru-RU': 'Сразу после поля ввода', - }, - contexts: [ - 'order/card', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/card:list.before': { - description: { - 'en-GB': 'Widget for the list of ordered items', - 'es-ES': 'Widget para la lista de artículos pedidos', - 'ru-RU': 'Виджет для списка позиций заказа', - }, - location: { - 'en-GB': 'Section start, right above the input fields', - 'es-ES': 'Inicio de la sección, justo encima de los campos de entrada', - 'ru-RU': 'Начало секции, над полями ввода', - }, - contexts: [ - 'order/card', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/card:list.after': { - description: { - 'en-GB': 'Widget for the list of ordered items', - 'es-ES': 'Widget para la lista de artículos pedidos', - 'ru-RU': 'Виджет для списка позиций заказа', - }, - location: { - 'en-GB': 'Section start, right under the list', - 'es-ES': 'Inicio de la sección, justo debajo de la lista', - 'ru-RU': 'Начало секции, под списком', - }, - contexts: [ - 'order/card', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/card:store.before': { - description: { - 'en-GB': 'Widget for the section with warehouse data', - 'es-ES': 'Widget para la sección con datos del almacén', - 'ru-RU': 'Виджет для секции с данными склада', - }, - location: { - 'en-GB': 'Section start, right above the input fields', - 'es-ES': 'Inicio de la sección, justo encima de los campos de entrada', - 'ru-RU': 'Начало секции, над полями ввода', - }, - contexts: [ - 'order/card', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/card:dimensions.before': { - description: { - 'en-GB': 'Widget for the section with dimensions and weight', - 'es-ES': 'Widget para la sección con dimensiones y peso', - 'ru-RU': 'Виджет для секции с данными габаритов и веса', - }, - location: { - 'en-GB': 'Section start, right above the input fields', - 'es-ES': 'Inicio de la sección, justo encima de los campos de entrada', - 'ru-RU': 'Начало секции, над полями ввода', - }, - contexts: [ - 'order/card', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/card:delivery.before': { - description: { - 'en-GB': 'Widget for the section with delivery data', - 'es-ES': 'Widget para la sección con datos de entrega', - 'ru-RU': 'Виджет для секции с данными доставки', - }, - location: { - 'en-GB': 'Section start, right above the input fields', - 'es-ES': 'Inicio de la sección, justo encima de los campos de entrada', - 'ru-RU': 'Начало секции, над полями ввода', - }, - contexts: [ - 'order/card', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/card:delivery.after': { - description: { - 'en-GB': 'Widget for the section with delivery data', - 'es-ES': 'Widget para la sección con datos de entrega', - 'ru-RU': 'Виджет для секции с данными доставки', - }, - location: { - 'en-GB': 'Section end, right under the input fields', - 'es-ES': 'Fin de la sección, justo debajo de los campos de entrada', - 'ru-RU': 'Конец секции, под полями ввода', - }, - contexts: [ - 'order/card', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/card:delivery.address': { - description: { - 'en-GB': 'Widget for delivery address input field', - 'es-ES': 'Widget para el campo de entrada de la dirección de entrega', - 'ru-RU': 'Виджет для поля ввода адреса доставки', - }, - location: { - 'en-GB': 'Right under the input field', - 'es-ES': 'Justo debajo del campo de entrada', - 'ru-RU': 'Под полем ввода адреса', - }, - contexts: [ - 'order/card', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/card:payment.before': { - description: { - 'en-GB': 'Widget for the section with payment data', - 'es-ES': 'Widget para la sección con datos de pago', - 'ru-RU': 'Виджет для секции с данными по оплате', - }, - location: { - 'en-GB': 'Section start, right above the input fields', - 'es-ES': 'Inicio de la sección, justo encima de los campos de entrada', - 'ru-RU': 'Начало секции, над полями ввода', - }, - contexts: [ - 'order/card', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/card:comment.manager.before': { - description: { - 'en-GB': 'Widget for the block "Manager comment"', - 'es-ES': 'Widget para el bloque "Comentario del asesor"', - 'ru-RU': 'Виджет для блока "Комментарии оператора"', - }, - location: { - 'en-GB': 'Section start, right above the input field', - 'es-ES': 'Inicio de la sección, justo encima del campo de entrada', - 'ru-RU': 'Начало секции, над полем ввода', - }, - contexts: [ - 'order/card', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/mg:list.before': { - description: { - 'en-GB': 'Widget for the block "Order items"', - 'es-ES': 'Widget para el bloque "Artículos del pedido"', - 'ru-RU': 'Виджет для блока "Состав заказа"', - }, - location: { - 'en-GB': 'Section start, right above the list of order items', - 'es-ES': 'Inicio de la sección, justo encima de la lista de artículos del pedido', - 'ru-RU': 'Начало секции, над списком товарных позиций', - }, - contexts: [ - 'order/card', - 'order/card:settings', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/mg:list.after': { - description: { - 'en-GB': 'Widget for the block "Order items"', - 'es-ES': 'Widget para el bloque "Artículos del pedido"', - 'ru-RU': 'Виджет для блока "Состав заказа"', - }, - location: { - 'en-GB': 'Section end, right after the list of order items and before the discount, privilege selection, etc. input fields', - 'es-ES': 'Fin de la sección, justo después de la lista de artículos del pedido y antes de los campos de entrada de descuento, selección de privilegios, etc.', - 'ru-RU': 'Конец секции, сразу после списка товарных позиций и до полей ввода скидки, выбора привилегии и т.п.', - }, - contexts: [ - 'order/card', - 'order/card:settings', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/mg:delivery.before': { - description: { - 'en-GB': 'Widget for the block "Delivery"', - 'es-ES': 'Widget para el bloque "Entrega"', - 'ru-RU': 'Виджет для блока "Доставка"', - }, - location: { - 'en-GB': 'Section start, right above the input field', - 'es-ES': 'Inicio de la sección, justo encima del campo de entrada', - 'ru-RU': 'Начало секции, над полем ввода', - }, - contexts: [ - 'order/card', - 'order/card:settings', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/mg:delivery.after': { - description: { - 'en-GB': 'Widget for the block "Delivery"', - 'es-ES': 'Widget para el bloque "Entrega"', - 'ru-RU': 'Виджет для блока "Доставка"', - }, - location: { - 'en-GB': 'Section end, right under the input fields', - 'es-ES': 'Fin de la sección, justo debajo de los campos de entrada', - 'ru-RU': 'Конец секции, под полями ввода', - }, - contexts: [ - 'order/card', - 'order/card:settings', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/mg:payment.before': { - description: { - 'en-GB': 'Widget for the block "Payment"', - 'es-ES': 'Widget para el bloque "Pago"', - 'ru-RU': 'Виджет для блока "Оплата"', - }, - location: { - 'en-GB': 'Section start, right above the input field', - 'es-ES': 'Inicio de la sección, justo encima del campo de entrada', - 'ru-RU': 'Начало секции, над полем ввода', - }, - contexts: [ - 'order/card', - 'order/card:settings', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, - 'order/mg:payment.after': { - description: { - 'en-GB': 'Widget for the block "Payment"', - 'es-ES': 'Widget para el bloque "Pago"', - 'ru-RU': 'Виджет для блока "Оплата"', - }, - location: { - 'en-GB': 'Section end, after the list of payments, controls, and custom fields', - 'es-ES': 'Fin de la sección, después de la lista de pagos, controles y campos personalizados', - 'ru-RU': 'Конец секции, после списка оплат, контролов и пользовательских полей', - }, - contexts: [ - 'order/card', - 'order/card:settings', - 'user/current', - 'settings', - ], - customContexts: [ - 'order', - ], - actions: [ - 'order/card', - ], - }, -} - -export const pageListDocumentation = [{ +export const pageListDocumentation: Array<{ + id: string; + description: TranslationList; +}> = [{ id: 'customer/card', description: { 'en-GB': 'Customer page', 'es-ES': 'Página del cliente', 'ru-RU': 'Страница клиента', - } as TranslationList, - targets: keysOf(targetListDocumentation).filter(target => target.startsWith('customer/card:')), + }, }, { id: 'order/card', description: { 'en-GB': 'Page with the order creation/editing form', 'es-ES': 'Página con el formulario de creación/edición de pedidos', 'ru-RU': 'Страница с формой создания/редактирования заказа', - } as TranslationList, - targets: keysOf(targetListDocumentation).filter(target => target.startsWith('order/card:')), + }, }, { id: 'order/mg', description: { 'en-GB': 'Page with the order creation/editing form in chats', 'es-ES': 'Página con el formulario de creación/edición de pedidos en los chats', 'ru-RU': 'Страница с формой создания/редактирования заказа в чатах', - } as TranslationList, - targets: keysOf(targetListDocumentation).filter(target => target.startsWith('order/mg:')), + }, }] diff --git a/package.json b/package.json index cb09e031..0dfc4510 100644 --- a/package.json +++ b/package.json @@ -19,14 +19,25 @@ "./dist/*": "./dist/*", "./types/*": "./types/*" }, - "bin": "./bin/embed-ui-update.mjs", + "bin": "./bin/embed-ui.mjs", + "files": [ + "bin", + "dist", + "index.d.ts", + "types", + "CHANGELOG.md", + "LICENSE", + "README.md" + ], "types": "index.d.ts", "workspaces": [ "packages/*" ], "scripts": { "build": "yarn build:code && yarn build:meta", - "build:code": "vite build", + "build:code": "yarn build:lib && yarn build:bin", + "build:lib": "vite build", + "build:bin": "vite build -c vite.config.bin.ts", "build:meta": "npx tsx scripts/build.meta.ts", "eslint": "eslint .", "test": "vitest --run", @@ -44,7 +55,9 @@ "@remote-ui/rpc": "^1.4.5", "@retailcrm/embed-ui-v1-components": "^0.9.21", "@retailcrm/embed-ui-v1-contexts": "^0.9.21", - "@retailcrm/embed-ui-v1-types": "^0.9.21" + "@retailcrm/embed-ui-v1-endpoint": "^0.9.21", + "@retailcrm/embed-ui-v1-types": "^0.9.21", + "yargs": "^17.7.2" }, "devDependencies": { "@eslint/eslintrc": "^3.3.3", @@ -84,8 +97,7 @@ "vite-plugin-dts": "^4.5.4", "vitest": "^4.1.3", "vue": "^3.5.32", - "vue-eslint-parser": "^10.4.0", - "yargs": "^17.7.2" + "vue-eslint-parser": "^10.4.0" }, "resolutions": { "handlebars": "^4.7.9" diff --git a/packages/v1-components/docs/profiles/pages/ModalSidebar.yml b/packages/v1-components/docs/profiles/pages/ModalSidebar.yml index 75513429..598b111f 100644 --- a/packages/v1-components/docs/profiles/pages/ModalSidebar.yml +++ b/packages/v1-components/docs/profiles/pages/ModalSidebar.yml @@ -36,7 +36,7 @@ examples:
- Open + Save diff --git a/packages/v1-endpoint/README.md b/packages/v1-endpoint/README.md index 31333d20..ceb13f00 100644 --- a/packages/v1-endpoint/README.md +++ b/packages/v1-endpoint/README.md @@ -2,9 +2,9 @@ [![npm version](https://img.shields.io/npm/v/@retailcrm/embed-ui-v1-endpoint.svg)](https://www.npmjs.com/package/@retailcrm/embed-ui-v1-endpoint) -`@retailcrm/embed-ui-v1-endpoint` помогает поднять endpoint для удалённых -виджетов и страниц в RetailCRM: принять вызовы host-части, смонтировать Vue -приложение в удалённый root и корректно освобождать ресурсы. +`@retailcrm/embed-ui-v1-endpoint` предоставляет endpoint API для встраиваемых +виджетов и страниц в RetailCRM: обработку вызовов host-части, монтирование Vue-приложения +в endpoint root и освобождение ресурсов. Пакет покрывает два сценария: @@ -28,19 +28,78 @@ const runner = defineRunner({ runEndpoint(runner) ``` -Для продакшен-использования обычно достаточно `runEndpoint(...)` в worker entry. +Для продакшен-использования обычно достаточно `runEndpoint(...)` в точке входа веб-воркера. Если нужен более низкоуровневый контроль транспорта — используйте `createEndpoint(...)`. -## Продвинутые гайды +## Документация Подробная документация по методам находится в каталоге [`docs/`](./docs/README.md): - [`defineRunner`](./docs/define-runner.md) — как объединить page и widget runners в один endpoint runner. -- [`definePageRunner`](./docs/define-page-runner.md) — как запускать remote-страницы по `code`. -- [`defineWidgetRunner`](./docs/define-widget-runner.md) — как запускать remote-виджеты по `target`. +- [`definePageRunner`](./docs/define-page-runner.md) — как запускать встраиваемые страницы по `code`. +- [`defineWidgetRunner`](./docs/define-widget-runner.md) — как запускать встраиваемые виджеты по `target`. - [`createEndpoint`](./docs/create-endpoint.md) — как вручную создать endpoint с transport и messenger. -- [`runEndpoint`](./docs/run-endpoint.md) — как поднять endpoint в worker entry одной строкой. +- [`runEndpoint`](./docs/run-endpoint.md) — как поднять endpoint в точке входа веб-воркера одной строкой. - [`targets` и `defineTarget`](./docs/targets.md) — как типизировать цели виджетов и маршрутизировать их по target. -- [`menu-placements`](./docs/menu-placements.md) — как описывать меню и пункты навигации для remote-страниц. -- [`page-routes`](./docs/page-routes.md) — как связывать page `code`, CRM route и `definePageRunner`. -- [`layout`](./docs/layout.md) — как выбирать layout-паттерны страниц, `modal sidebar` и `modal window`, и из каких `v1-components` их собирать. +- [`menu-placements`](./docs/menu-placements.md) — как описывать меню и пункты навигации для встраиваемых страниц. +- [`page-routes`](./docs/page-routes.md) — как связывать page `code`, CRM-маршрут и `definePageRunner`. +- [`layout`](./docs/layout.md) — как выбирать паттерны компоновки страниц, `modal sidebar` и `modal window`, и из каких `v1-components` их собирать. + +## MCP для AI-ассистентов + +Пакет поставляет MCP-сервер с AI-friendly описаниями встроенных widget targets. +Сервер читает сгенерированные YAML-профили из `docs/targets/*.yml` и отдаёт их как MCP resources. + +Запуск через опубликованный пакет: + +```bash +npx -p @retailcrm/embed-ui-v1-endpoint embed-ui-v1-endpoint-mcp +``` + +Пример stdio-конфига для MCP-клиента: + +```json +{ + "command": "npx", + "args": ["-y", "-p", "@retailcrm/embed-ui-v1-endpoint", "embed-ui-v1-endpoint-mcp"] +} +``` + +Базовые resources: + +- `embed-ui-v1-endpoint://targets` — JSON-индекс всех target profiles. +- `embed-ui-v1-endpoint://targets/` — YAML-профиль конкретного target. + +## AI и инициализация `AGENTS.md` + +Чтобы агент понимал, когда использовать MCP-сервер пакета, можно добавить в +целевой проект секцию с инструкциями: + +```bash +npx @retailcrm/embed-ui-v1-endpoint init-agents +``` + +Если `AGENTS.md` ещё нет, команда создаст файл. Если файл уже есть, команда +допишет в конец английский блок для `@retailcrm/embed-ui-v1-endpoint`, если +такого блока там ещё нет. С `--force` можно обновить уже существующий блок +пакета. + +## Инициализация MCP-конфига + +Пакет также может сам добавить project-level MCP-настройки в целевой проект: + +```bash +npx @retailcrm/embed-ui-v1-endpoint init-config +``` + +Команда создаёт или дополняет корневой `.mcp.json`, добавляет заметку в +`README.md` и не дублирует уже существующую настройку. Клиентские project-level +конфиги создаются только явно: + +```bash +npx @retailcrm/embed-ui-v1-endpoint init-config --mcp-client-configs cursor,junie,vscode +``` + +С `--force` можно обновить уже существующие управляемые записи. Команда +обновляет только запись `retailcrm-embed-ui-v1-endpoint`, а остальные серверы и +пользовательские настройки клиентских конфигов оставляет без изменений. diff --git a/packages/v1-endpoint/bin/embed-ui-v1-endpoint-mcp.mjs b/packages/v1-endpoint/bin/embed-ui-v1-endpoint-mcp.mjs new file mode 100755 index 00000000..7ae9e21a --- /dev/null +++ b/packages/v1-endpoint/bin/embed-ui-v1-endpoint-mcp.mjs @@ -0,0 +1,10 @@ +#!/usr/bin/env node + +import { runEndpointMcpServer } from '../dist/mcp/server.js' + +try { + await runEndpointMcpServer() +} catch (error) { + console.error(error) + process.exit(1) +} diff --git a/packages/v1-endpoint/bin/embed-ui-v1-endpoint.mjs b/packages/v1-endpoint/bin/embed-ui-v1-endpoint.mjs new file mode 100755 index 00000000..10438392 --- /dev/null +++ b/packages/v1-endpoint/bin/embed-ui-v1-endpoint.mjs @@ -0,0 +1,416 @@ +#!/usr/bin/env node + +import fs from 'node:fs' +import path from 'node:path' +import process from 'node:process' + +const PACKAGE_NAME = '@retailcrm/embed-ui-v1-endpoint' +const DEFAULT_NEWLINE = '\n' +const AGENTS_SECTION_HEADER = '## @retailcrm/embed-ui-v1-endpoint' +const README_MCP_SECTION_HEADER = '## MCP For AI Assistants' +const README_MCP_MARKER = 'embed-ui-v1-endpoint://targets' +const MCP_SERVER_NAME = 'retailcrm-embed-ui-v1-endpoint' +const MCP_SERVER_CONFIG = { + command: 'npx', + args: ['-y', '-p', PACKAGE_NAME, 'embed-ui-v1-endpoint-mcp'], +} +const MCP_CLIENT_CONFIGS = { + cursor: { + filePath: '.cursor/mcp.json', + rootField: 'mcpServers', + }, + junie: { + filePath: '.junie/mcp/mcp.json', + rootField: 'mcpServers', + }, + vscode: { + filePath: '.vscode/mcp.json', + rootField: 'servers', + }, +} + +const HELP_TEXT = `Usage: + npx ${PACKAGE_NAME} init-agents [target] [options] + npx ${PACKAGE_NAME} init-config [target] [options] + +Options: + -f, --force Replace existing managed sections and MCP server entries + --mcp-client-configs Comma-separated MCP client configs to create (cursor,junie,vscode) + --dry-run Print planned config changes without writing files + -h, --help Show this help + +Examples: + npx ${PACKAGE_NAME} init-agents + npx ${PACKAGE_NAME} init-agents ./my-project + npx ${PACKAGE_NAME} init-agents --force + npx ${PACKAGE_NAME} init-config ./my-project + npx ${PACKAGE_NAME} init-config ./my-project --mcp-client-configs cursor,junie,vscode +` + +const parseArgs = (argv) => { + const options = { + command: null, + target: process.cwd(), + force: false, + dryRun: false, + mcpClientConfigs: [], + } + + const positionals = [] + + for (let index = 0; index < argv.length; index++) { + const argument = argv[index] + + if (argument === '-h' || argument === '--help') { + console.log(HELP_TEXT) + process.exit(0) + } + + if (argument === '-f' || argument === '--force') { + options.force = true + continue + } + + if (argument === '--dry-run') { + options.dryRun = true + continue + } + + if (argument === '--mcp-client-configs') { + const value = argv[index + 1] + if (!value || value.startsWith('-')) { + throw new Error('--mcp-client-configs requires a comma-separated value') + } + + options.mcpClientConfigs = value + .split(',') + .map((entry) => entry.trim()) + .filter(Boolean) + index++ + continue + } + + if (argument.startsWith('-')) { + throw new Error(`Unknown option: ${argument}`) + } + + positionals.push(argument) + } + + if (!positionals.length) { + throw new Error('Command is required') + } + + options.command = positionals[0] + + if (positionals.length >= 2) { + options.target = path.resolve(process.cwd(), positionals[1]) + } + + if (positionals.length > 2) { + throw new Error('Too many positional arguments') + } + + return options +} + +const createAgentsSection = () => { + return `${AGENTS_SECTION_HEADER} + +When working with \`${PACKAGE_NAME}\` in this project: + +1. Read \`./node_modules/${PACKAGE_NAME}/README.md\`. +2. Then read the relevant guide from \`./node_modules/${PACKAGE_NAME}/docs/README.md\`. +3. Use documented public entrypoints instead of package internals: + - \`${PACKAGE_NAME}/remote\` + - \`${PACKAGE_NAME}/common/targets\` +4. Do not import from \`${PACKAGE_NAME}/dist/*\`, source files, or repository-only paths. +5. When the task involves widget targets, target placement, target contexts, target metadata, or choosing a target, use the package MCP server if it is available. +6. First read \`embed-ui-v1-endpoint://targets\` to discover available target profiles. +7. Then read the relevant \`embed-ui-v1-endpoint://targets/\` resource before answering or changing code related to that target. +8. If MCP resources are not available, use the generated YAML profiles from \`./node_modules/${PACKAGE_NAME}/docs/targets/*.yml\` as the fallback source. +9. Prefer target profiles over guessing target placement, contexts, or semantic intent from names alone. + +Suggested MCP stdio server configuration: + +\`\`\`json +{ + "command": "npx", + "args": ["-y", "-p", "${PACKAGE_NAME}", "embed-ui-v1-endpoint-mcp"] +} +\`\`\` +` +} + +const createMcpReadmeSection = (clientConfigs) => { + const clientConfigText = clientConfigs.length + ? `Client MCP configs were also requested: ${clientConfigs.map((clientConfig) => `\`${clientConfig}\``).join(', ')}. Review the generated files and restart the AI client if it is already open.` + : 'Client MCP configs are not created by default. For supported project-level configs, rerun init with `--mcp-client-configs cursor,junie,vscode`.' + + return `${README_MCP_SECTION_HEADER} + +The project has an MCP server configuration for \`${PACKAGE_NAME}\`. +It exposes AI-friendly widget target descriptions as MCP resources. + +Basic check: + +\`\`\`bash +npx -p ${PACKAGE_NAME} embed-ui-v1-endpoint-mcp +\`\`\` + +Primary resources: + +- \`${README_MCP_MARKER}\` is the widget target index. +- \`embed-ui-v1-endpoint://targets/\` is a YAML profile for one target. + +${clientConfigText} + +### User-Level MCP Clients + +Some clients store MCP servers in a user-level config outside this repository. Init does not edit +those files. Add the same server manually and restart the client. + +Claude Desktop config paths: + +- macOS: \`~/Library/Application Support/Claude/claude_desktop_config.json\` +- Windows: \`%APPDATA%\\Claude\\claude_desktop_config.json\` + +Config snippet: + +\`\`\`json +{ + "mcpServers": { + "${MCP_SERVER_NAME}": { + "command": "npx", + "args": ["-y", "-p", "${PACKAGE_NAME}", "embed-ui-v1-endpoint-mcp"] + } + } +} +\`\`\` +` +} + +const createAgentsTemplate = () => { + return `# AGENTS.md + +${createAgentsSection()}` + DEFAULT_NEWLINE +} + +const hasPackageSection = (content) => content.includes(AGENTS_SECTION_HEADER) + +const appendSection = (content, section) => { + const trimmed = content.replace(/\s+$/u, '') + + if (!trimmed.length) { + return `${section}${DEFAULT_NEWLINE}` + } + + return `${trimmed}${DEFAULT_NEWLINE}${DEFAULT_NEWLINE}${section}${DEFAULT_NEWLINE}` +} + +const replaceSection = (content, section) => { + const escapedHeader = AGENTS_SECTION_HEADER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + const sectionPattern = new RegExp(`${escapedHeader}[\\s\\S]*?(?=\\n##\\s|$)`, 'u') + + if (!sectionPattern.test(content)) { + return appendSection(content, section) + } + + return content + .replace(sectionPattern, section.trimEnd()) + .replace(/\s+$/u, '') + DEFAULT_NEWLINE +} + +const replaceReadmeMcpSection = (content, section) => { + const escapedHeader = README_MCP_SECTION_HEADER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + const sectionPattern = new RegExp(`${escapedHeader}[\\s\\S]*?(?=\\n##\\s|$)`, 'u') + + if (!sectionPattern.test(content)) { + return appendSection(content, section) + } + + return content + .replace(sectionPattern, section.trimEnd()) + .replace(/\s+$/u, '') + DEFAULT_NEWLINE +} + +const readJsonObject = (filePath) => { + if (!fs.existsSync(filePath)) { + return {} + } + + const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8')) + if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) { + throw new Error(`${filePath} must contain a JSON object`) + } + + return parsed +} + +const ensureObjectField = (object, field, filePath) => { + const value = object[field] + + if (!value) { + object[field] = {} + return object[field] + } + + if (typeof value !== 'object' || Array.isArray(value)) { + throw new Error(`${filePath} field "${field}" must be a JSON object`) + } + + return value +} + +const writeJson = (filePath, value, dryRun) => { + if (dryRun) { + return + } + + fs.mkdirSync(path.dirname(filePath), { recursive: true }) + fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}${DEFAULT_NEWLINE}`, 'utf8') +} + +const initAgents = (target, force) => { + if (!fs.existsSync(target)) { + throw new Error(`Target path does not exist: ${target}`) + } + + const stat = fs.statSync(target) + + if (!stat.isDirectory()) { + throw new Error(`Target path is not a directory: ${target}`) + } + + const agentsPath = path.join(target, 'AGENTS.md') + const section = createAgentsSection() + + if (!fs.existsSync(agentsPath)) { + fs.writeFileSync(agentsPath, createAgentsTemplate(), 'utf8') + + console.log(`AGENTS.md was created at ${agentsPath}`) + console.log('Next step: review it and adjust project-specific rules if needed.') + return + } + + const currentContent = fs.readFileSync(agentsPath, 'utf8') + + if (force) { + fs.writeFileSync(agentsPath, replaceSection(currentContent, section), 'utf8') + console.log(`AGENTS.md was updated at ${agentsPath}`) + console.log(`The ${PACKAGE_NAME} section was refreshed.`) + return + } + + if (hasPackageSection(currentContent)) { + console.log(`AGENTS.md already contains a ${PACKAGE_NAME} section at ${agentsPath}`) + console.log('Nothing was changed. Re-run with --force to refresh that section.') + return + } + + fs.writeFileSync(agentsPath, appendSection(currentContent, section), 'utf8') + + console.log(`AGENTS.md was updated at ${agentsPath}`) + console.log(`The ${PACKAGE_NAME} instructions were appended to the end of the file.`) +} + +const writeMcpServerConfig = (target, relativePath, rootField, options) => { + const filePath = path.join(target, relativePath) + const fileExists = fs.existsSync(filePath) + const config = readJsonObject(filePath) + const servers = ensureObjectField(config, rootField, filePath) + + if (servers[MCP_SERVER_NAME] && !options.force) { + console.log(`${relativePath} already contains ${MCP_SERVER_NAME}`) + console.log('Nothing was changed. Re-run with --force to refresh that server entry.') + return + } + + servers[MCP_SERVER_NAME] = MCP_SERVER_CONFIG + writeJson(filePath, config, options.dryRun) + + const action = fileExists ? 'updated' : 'created' + console.log(`${relativePath} ${options.dryRun ? `would be ${action}` : `was ${action}`}`) +} + +const resolveMcpClientConfigs = (tokens) => { + for (const token of tokens) { + if (!(token in MCP_CLIENT_CONFIGS)) { + throw new Error(`Unknown MCP client config: ${token}`) + } + } + + return tokens +} + +const updateMcpReadmeNotes = (target, clientConfigs, options) => { + const readmePath = path.join(target, 'README.md') + const fileExists = fs.existsSync(readmePath) + const currentContent = fileExists + ? fs.readFileSync(readmePath, 'utf8') + : '# README.md\n' + const section = createMcpReadmeSection(clientConfigs) + + if (currentContent.includes(README_MCP_MARKER) && !options.force) { + console.log(`README.md already contains MCP setup notes at ${readmePath}`) + console.log('Nothing was changed. Re-run with --force to refresh that section.') + return + } + + const nextContent = replaceReadmeMcpSection(currentContent, section) + + if (!options.dryRun) { + fs.writeFileSync(readmePath, nextContent, 'utf8') + } + + const action = fileExists ? 'updated' : 'created' + console.log(`README.md ${options.dryRun ? `would be ${action}` : `was ${action}`} with MCP setup notes`) +} + +const initConfig = (target, options) => { + if (!fs.existsSync(target)) { + throw new Error(`Target path does not exist: ${target}`) + } + + const stat = fs.statSync(target) + + if (!stat.isDirectory()) { + throw new Error(`Target path is not a directory: ${target}`) + } + + const clientConfigs = resolveMcpClientConfigs(options.mcpClientConfigs) + + writeMcpServerConfig(target, '.mcp.json', 'mcpServers', options) + + for (const clientConfig of clientConfigs) { + const config = MCP_CLIENT_CONFIGS[clientConfig] + writeMcpServerConfig(target, config.filePath, config.rootField, options) + } + + updateMcpReadmeNotes(target, clientConfigs, options) +} + +const main = () => { + try { + const options = parseArgs(process.argv.slice(2)) + + if (options.command === 'init-agents') { + initAgents(options.target, options.force) + return + } + + if (options.command === 'init-config') { + initConfig(options.target, options) + return + } + + throw new Error(`Unknown command: ${options.command}`) + } catch (error) { + console.error(error instanceof Error ? error.message : String(error)) + console.error('') + console.error(HELP_TEXT) + process.exit(1) + } +} + +main() diff --git a/packages/v1-endpoint/docs/README.md b/packages/v1-endpoint/docs/README.md index c14881d9..8b33b8e2 100644 --- a/packages/v1-endpoint/docs/README.md +++ b/packages/v1-endpoint/docs/README.md @@ -1,18 +1,20 @@ # Документация `@retailcrm/embed-ui-v1-endpoint` -В этом каталоге собраны продвинутые гайды по публичному API `v1-endpoint`. +В этом каталоге собраны практические гайды по публичному API `v1-endpoint`. ## По методам - [`defineRunner`](./define-runner.md) — объединение page/widget runners в один endpoint runner. -- [`definePageRunner`](./define-page-runner.md) — запуск remote-страниц по `code`. -- [`defineWidgetRunner`](./define-widget-runner.md) — запуск remote-виджетов по `target`. +- [`definePageRunner`](./define-page-runner.md) — запуск встраиваемых страниц по `code`. +- [`defineWidgetRunner`](./define-widget-runner.md) — запуск встраиваемых виджетов по `target`. - [`createEndpoint`](./create-endpoint.md) — ручное создание endpoint с transport/messenger. - [`runEndpoint`](./run-endpoint.md) — запуск endpoint в worker одной строкой. ## Дополнительно - [`targets` и `defineTarget`](./targets.md) — типизированные цели для виджетов. -- [`menu-placements`](./menu-placements.md) — как описывать меню и пункты навигации, из которых открываются remote-страницы. -- [`page-routes`](./page-routes.md) — как связывать page `code`, CRM route и `definePageRunner`. -- [`layout`](./layout.md) — практический гайд по layout-паттернам страниц, шторок и модалок. +- [`targets/*.yml`](./targets/) — сгенерированные AI-friendly описания встроенных widget targets на английском. +- MCP-сервер `embed-ui-v1-endpoint-mcp` — поставляемый stdio server, который отдаёт `targets/*.yml` как MCP resources. +- [`menu-placements`](./menu-placements.md) — как описывать меню и пункты навигации, из которых открываются встраиваемые страницы. +- [`page-routes`](./page-routes.md) — как связывать page `code`, CRM-маршрут и `definePageRunner`. +- [`layout`](./layout.md) — практический гайд по паттернам компоновки страниц, шторок и модалок. diff --git a/packages/v1-endpoint/docs/create-endpoint.md b/packages/v1-endpoint/docs/create-endpoint.md index 4807f5e6..0e1b4af5 100644 --- a/packages/v1-endpoint/docs/create-endpoint.md +++ b/packages/v1-endpoint/docs/create-endpoint.md @@ -1,7 +1,7 @@ # `createEndpoint` -`createEndpoint` связывает runner и transport (messenger), после чего -экспортирует endpoint API (`run`, `release`, `reset`) через `@remote-ui/rpc`. +`createEndpoint` связывает runner и transport (`messenger`) и экспортирует +endpoint API (`run`, `release`, `reset`) через `@remote-ui/rpc`. ## Сигнатура @@ -15,15 +15,15 @@ createEndpoint( ): Endpoint ``` -## Что делает под капотом +## Поведение При `run(...)`: -1. сбрасывает предыдущий mount для того же `id` (widget) или `code` (page), -2. поднимает remote root (`mountEndpointRoot`), +1. сбрасывает предыдущее монтирование для того же `id` (widget) или `code` (page), +2. поднимает endpoint root (`mountEndpointRoot`), 3. создаёт `pinia` и инжектит endpoint/context accessors, 4. вызывает нужный runner (`page.run` или `widget.run`), -5. сохраняет destroy-функцию в registry. +5. сохраняет destroy-функцию в реестре. При `release(...)`: @@ -33,7 +33,7 @@ createEndpoint( - вызывает destroy для всех активных page/widget инстансов. -## Пример (низкоуровневый) +## Пример ```ts import { defineRunner, createEndpoint } from '@retailcrm/embed-ui-v1-endpoint/remote' @@ -43,12 +43,10 @@ const runner = defineRunner({ widgets: [MyWidgetRoot], }) -// messenger зависит от среды исполнения createEndpoint(runner, self as unknown as MessageEndpoint) ``` ## Когда нужен именно `createEndpoint` - Нужна кастомная интеграция transport-слоя. -- Вы сами контролируете, где и как создаётся `MessageEndpoint`. -- Нужно использовать endpoint не через стандартный worker-entry сценарий. +- Нужно использовать endpoint не через стандартную точку входа веб-воркера. diff --git a/packages/v1-endpoint/docs/define-page-runner.md b/packages/v1-endpoint/docs/define-page-runner.md index 954de576..23bc7496 100644 --- a/packages/v1-endpoint/docs/define-page-runner.md +++ b/packages/v1-endpoint/docs/define-page-runner.md @@ -1,6 +1,6 @@ # `definePageRunner` -`definePageRunner` создаёт runner для remote-страниц. +`definePageRunner` создаёт runner для встраиваемых страниц. При запуске в компонент пробрасывается проп `code`. ## Перегрузки @@ -58,5 +58,5 @@ const pageRunner = definePageRunner(PageRoot, async (app, pinia) => { Читайте также: -- [`page-routes`](./page-routes.md) — как связать page `code`, CRM route и компонент страницы. -- [`menu-placements`](./menu-placements.md) — как описывать пункты меню, которые открывают remote-страницы. +- [`page-routes`](./page-routes.md) — как связать page `code`, CRM-маршрут и компонент страницы. +- [`menu-placements`](./menu-placements.md) — как описывать пункты меню, которые открывают встраиваемые страницы. diff --git a/packages/v1-endpoint/docs/define-widget-runner.md b/packages/v1-endpoint/docs/define-widget-runner.md index cfd3b87f..da72c8ed 100644 --- a/packages/v1-endpoint/docs/define-widget-runner.md +++ b/packages/v1-endpoint/docs/define-widget-runner.md @@ -1,6 +1,6 @@ # `defineWidgetRunner` -`defineWidgetRunner` создаёт runner для remote-виджетов. +`defineWidgetRunner` создаёт runner для встраиваемых виджетов. При запуске в компонент пробрасывается проп `target`. ## Перегрузки @@ -47,7 +47,7 @@ const widgetRunner = defineWidgetRunner({ ## `beforeMount` -`beforeMount` работает аналогично page-раннеру: выполняется перед mount и после подключения `pinia`. +`beforeMount` работает аналогично page-раннеру: выполняется перед монтированием и после подключения `pinia`. ```ts const widgetRunner = defineWidgetRunner(WidgetRoot, async (app, pinia) => { diff --git a/packages/v1-endpoint/docs/layout.md b/packages/v1-endpoint/docs/layout.md index 4b2736d1..9eb75ece 100644 --- a/packages/v1-endpoint/docs/layout.md +++ b/packages/v1-endpoint/docs/layout.md @@ -1,14 +1,9 @@ -# Гайд по layout для страниц и связанных экранов +# Компоновка страниц и связанных экранов -Этот документ собирает в одном месте практические правила по тому, как проектировать -страницы для `@retailcrm/embed-ui-v1-endpoint`: списки, карточки, страницы с несколькими -колонками, страницы с collapse-блоками, а также случаи, когда вместо полноценной страницы -следует использовать `modal sidebar` или `modal window`. +Практические правила для встраиваемых страниц `@retailcrm/embed-ui-v1-endpoint`: списков, +карточек, многоколоночных страниц, collapse-страниц, `modal sidebar` и `modal window`. -Это не API-справка по `v1-endpoint`, а UX/layout guide для людей, которые собирают remote-page -через `definePageRunner(...)` и хотят держаться общего визуального языка CRM. - -## Базовая ментальная модель +## Структура страницы Обычная страница в CRM чаще всего состоит из таких зон: @@ -18,19 +13,14 @@ 4. Основной контент на белых подложках. 5. Опционально: нижняя панель сохранения. -Если экран перестаёт быть удобной полноценной страницей, его не следует усложнять бесконечно; -в этом случае его следует переводить в другой паттерн: `modal sidebar` или `modal window`. +Если сценарий перестаёт быть удобной полноценной страницей, используйте другой паттерн: +`modal sidebar` или `modal window`. ## Термины -В этом документе используются следующие термины: - - `modal sidebar` — боковая выезжающая панель. В разговорной речи может называться “шторкой”. - `modal window` — всплывающее модальное окно. В разговорной речи может называться “модалкой”. -- `страница` — основной route-level экран, который занимает центральную рабочую область CRM. - -Далее по тексту предпочтительно используются термины `modal sidebar` и `modal window`, потому что -они напрямую соотносятся с компонентами `UiModalSidebar`, `UiModalWindow` и `UiModalWindowSurface`. +- `страница` — основной экран уровня маршрута, который занимает центральную рабочую область CRM. ## Общие правила @@ -246,10 +236,6 @@ - Дополнительная информация, которую не хочется разворачивать в отдельную страницу. - Сценарии вроде задач, уведомлений, нового обращения, редактирования шага. -### Размеры - -- Часто используется одна из двух ширин: `720px` или `416px`. - ### Основные части 1. Закреплённый `header`. @@ -275,7 +261,8 @@ - Контент в двух колонках на разных подложках. - Громоздкие, большие и сложные интерфейсы. -Если экран фактически превращается в полноценную страницу или большую предметную область, `modal sidebar` уже не является подходящим выбором. +Если экран превращается в полноценную страницу или большую предметную область, `modal sidebar` +уже не подходит. ## 5. Когда вместо страницы нужен `modal window` @@ -283,12 +270,7 @@ - Для отображения большой вспомогательной таблицы “по месту”. - Для дополнительных настроек, когда `modal sidebar` уже не хватает. -- Для сценариев просмотра или выбора, не заслуживающих отдельного route-level экрана. - -### Размеры - -- Обычный `modal window` шириной около `960px`. -- Или полноэкранный режим с внешними отступами по краям. +- Для сценариев просмотра или выбора, не заслуживающих отдельного экрана уровня маршрута. ### Основные части @@ -328,9 +310,9 @@ - требуется быстро завершить отдельный шаг без перехода на полноценную страницу; - `modal sidebar` уже тесен, но полноценная страница всё ещё избыточна. -## Сопоставление с `embed-ui` +## Компонентная карта -Ниже не жёсткий contract, а практичное соответствие layout-паттернов библиотечным примитивам: +Соответствие паттернов компоновки публичным компонентам: - заголовок страницы: `UiPageHeader`; - верхние actions: `UiButton`, `UiToolbarButton`, `UiToolbarLink`; @@ -341,9 +323,7 @@ - `modal sidebar`: `UiModalSidebar`; - `modal window`: `UiModalWindow` и `UiModalWindowSurface`. -## Чеклист перед реализацией страницы - -Перед тем как собирать новый page runner, полезно ответить на несколько вопросов: +## Чеклист перед реализацией 1. Это действительно страница, а не `modal sidebar` и не `modal window`? 2. Это список, карточка, карточка с колонками или collapse-настройки? @@ -352,12 +332,9 @@ 5. Не перегружен ли экран количеством primary-действий? 6. Держатся ли отступы и расстояния сетки `4px`? -Если на эти вопросы нет уверенного ответа, сначала следует выбрать подходящий layout-паттерн, -а уже потом собирать компоненты и wiring через `v1-endpoint`. - --- -Примечание: все упоминаемые в этом документе компоненты вида `Ui*` относятся к пакету +Все упоминаемые компоненты вида `Ui*` относятся к пакету `@retailcrm/embed-ui-v1-components`. Термины `modal sidebar`, `modal window`, tabs, collapse-группы, таблицы, поля и другие layout-примитивы в этом гайде привязаны именно к публичным компонентам из `v1-components`, а не к произвольной внутренней терминологии проекта. diff --git a/packages/v1-endpoint/docs/menu-placements.md b/packages/v1-endpoint/docs/menu-placements.md index cef559cf..46aa4307 100644 --- a/packages/v1-endpoint/docs/menu-placements.md +++ b/packages/v1-endpoint/docs/menu-placements.md @@ -1,9 +1,8 @@ # Меню и точки входа страниц -Этот справочник описывает, как документировать меню и пункты навигации, из которых запускаются -remote-страницы расширения. +Справочник для описания меню и пунктов навигации, из которых запускаются встраиваемые страницы расширения. -Важно: `v1-endpoint` не экспортирует типизированный registry CRM-меню. Пакет отвечает за запуск +`v1-endpoint` не экспортирует типизированный реестр CRM-меню. Пакет отвечает за запуск страницы по `code`, а список меню, подпунктов и их видимость задаются на стороне host/manifest конкретного расширения. @@ -11,13 +10,13 @@ remote-страницы расширения. - `menu placement` — зона CRM, куда host добавляет пункт навигации. - `menu item` — конкретный пункт меню, который видит пользователь. -- `page code` — стабильный код remote-страницы, который host передаёт в `definePageRunner`. -- `route` — маршрут CRM или route name, через который host открывает страницу. +- `page code` — стабильный код встраиваемой страницы, который host передаёт в `definePageRunner`. +- `route` — маршрут CRM или имя маршрута, через который host открывает страницу. -`menu item` не равен `target`. Меню открывает полноценную remote-страницу по `code`, а `target` +`menu item` не равен `target`. Меню открывает полноценную встраиваемую страницу по `code`, а `target` используется для виджетов, которые встраиваются внутрь уже существующей CRM-страницы. -## Что нужно фиксировать в справочнике проекта +## Что фиксировать в справочнике проекта Для каждого пункта меню указывайте: @@ -26,14 +25,13 @@ remote-страницы расширения. | `placement` | Зона CRM, где находится пункт меню. | | `item code` | Стабильный код пункта меню в host/manifest. | | `label` | Пользовательское название пункта меню. | -| `page code` | Код remote-страницы, который получит `definePageRunner`. | -| `route` | Имя или путь CRM-маршрута, если пункт открывается через host routing. | +| `page code` | Код встраиваемой страницы, который получит `definePageRunner`. | +| `route` | Имя или путь CRM-маршрута, если пункт открывается через маршрутизацию host-части. | | `visibility` | Условия показа: права, настройки, тариф, доступность фичи. | ## Пример справочника меню -Это пример формата. Конкретные `placement`, `item code` и `route` нужно брать из host/manifest -расширения. +Конкретные `placement`, `item code` и `route` нужно брать из host/manifest расширения. | Placement | Item code | Label | Page code | Route | Когда использовать | | --- | --- | --- | --- | --- | --- | @@ -64,8 +62,8 @@ const pageRunner = definePageRunner({ Читайте также: -- [`page-routes`](./page-routes.md) — как описывать page `code` и CRM route. -- [`definePageRunner`](./define-page-runner.md) — как remote-страница получает `code`. +- [`page-routes`](./page-routes.md) — как описывать page `code` и CRM-маршрут. +- [`definePageRunner`](./define-page-runner.md) — как встраиваемая страница получает `code`. - [`targets`](./targets.md) — точки встраивания виджетов, не пунктов меню. - [`layout`](./layout.md) — когда делать полноценную страницу, а когда `modal sidebar` или `modal window`. - [`UiMenuItem`](../../v1-components/docs/profiles/UiMenuItem.yml) — компонент строки меню внутри UI расширения. diff --git a/packages/v1-endpoint/docs/page-routes.md b/packages/v1-endpoint/docs/page-routes.md index 9ec79d2a..445ec3ff 100644 --- a/packages/v1-endpoint/docs/page-routes.md +++ b/packages/v1-endpoint/docs/page-routes.md @@ -1,16 +1,15 @@ -# Роуты страниц +# Маршруты страниц -Remote-страницы в `v1-endpoint` запускаются по `code`. Этот `code` приходит от host и пробрасывается -в компонент через `definePageRunner`. +Встраиваемые страницы в `v1-endpoint` запускаются по `code`. Host передаёт `code`, а +`definePageRunner` пробрасывает его в компонент. -`v1-endpoint` не задаёт фиксированный список page routes. Список страниц и CRM-маршрутов принадлежит +`v1-endpoint` не задаёт фиксированный список маршрутов страниц. Список страниц и CRM-маршрутов принадлежит host/manifest конкретного расширения, поэтому его нужно хранить в справочнике проекта рядом с кодом расширения. ## Что такое `page code` -`page code` — стабильный идентификатор remote-страницы внутри расширения. Он отвечает на вопрос: -«какую страницу расширения нужно смонтировать?». +`page code` — стабильный идентификатор встраиваемой страницы внутри расширения. Пример: @@ -37,11 +36,10 @@ defineProps<{ ## Что такое `route` -`route` — CRM-маршрут или route name, через который host открывает страницу. В remote-коде route -может использоваться для переходов через `HostApi.goTo(route, params)`. +`route` — CRM-маршрут или имя маршрута, через который host открывает страницу. В коде расширения +route может использоваться для переходов через `HostApi.goTo(route, params)`. -Данные Symfony JS router доступны в контексте `settings` в поле `system.routing`. Это полезно, -когда нужно проверить доступные route names или собрать ссылку тем же routing data, что отдаёт host. +Данные Symfony JS router доступны в контексте `settings` в поле `system.routing`. ```ts import { useContext as useSettingsContext } from '@retailcrm/embed-ui-v1-contexts/remote/settings' @@ -51,9 +49,9 @@ const settings = useSettingsContext() console.log(settings['system.routing'].routes) ``` -## Пример справочника роутов страниц +## Пример справочника маршрутов страниц -Это пример формата. Конкретные `code`, `route` и параметры нужно брать из host/manifest расширения. +Конкретные `code`, `route` и параметры нужно брать из host/manifest расширения. | Page code | Route | Params | Открывается из | Компонент | | --- | --- | --- | --- | --- | @@ -61,7 +59,7 @@ console.log(settings['system.routing'].routes) | `integration-settings` | `embed.page.integration_settings` | `{}` | `settings / integration-settings` | `IntegrationSettingsPage.vue` | | `customer-tools` | `embed.page.customer_tools` | `{ customerId }` | `customer/card:actions / customer-tools` | `CustomerToolsPage.vue` | -## Переход на CRM route +## Переход на CRM-маршрут Если странице нужен переход на другой CRM-маршрут, используйте host API, а не прямую сборку URL. Способ получения `HostApi` зависит от host-интеграции проекта, но сам публичный контракт выглядит так: @@ -76,7 +74,7 @@ const openSettings = (host: HostApi) => { Читайте также: -- [`menu-placements`](./menu-placements.md) — как связать пункт меню, page `code` и route. +- [`menu-placements`](./menu-placements.md) — как связать пункт меню, page `code` и маршрут. - [`definePageRunner`](./define-page-runner.md) — как page `code` попадает в компонент. - [`settings context`](../../v1-contexts/docs/ru/CONCEPT.md) — общий принцип работы контекстов. - [`HostApi`](../../v1-types/host.d.ts) — публичный тип host API с `goTo`. diff --git a/packages/v1-endpoint/docs/run-endpoint.md b/packages/v1-endpoint/docs/run-endpoint.md index cc637ecb..0992b334 100644 --- a/packages/v1-endpoint/docs/run-endpoint.md +++ b/packages/v1-endpoint/docs/run-endpoint.md @@ -1,6 +1,6 @@ # `runEndpoint` -`runEndpoint` — shortcut для worker entry: +`runEndpoint` — краткая форма для точки входа веб-воркера: он вызывает `createEndpoint(runner, self as Worker)`. ## Сигнатура @@ -28,10 +28,10 @@ runEndpoint(runner) ## Когда использовать -- Почти всегда, если endpoint запускается как web worker. +- Почти всегда, если endpoint запускается как веб-воркер. - Когда не нужен ручной контроль над messenger/transport. ## Когда лучше `createEndpoint` -- Когда transport создаётся не от `self` worker. -- Когда у вас кастомный runtime/bridge между host и remote. +- Когда transport создаётся не от `self` веб-воркера. +- Когда у вас кастомная среда выполнения или bridge между host и remote. diff --git a/packages/v1-endpoint/docs/targets.md b/packages/v1-endpoint/docs/targets.md index f0125bff..9d246364 100644 --- a/packages/v1-endpoint/docs/targets.md +++ b/packages/v1-endpoint/docs/targets.md @@ -7,12 +7,14 @@ - `targets` — словарь встроенных target-конфигураций. - `TargetName` — union всех ключей `targets`. -- `defineTarget(id, contexts)` — helper для объявления target с типами контекстов. +- `TargetList` — словарь `target -> SchemaList`, выведенный из `targets[target].contexts`. +- `defineTarget(id, config)` — helper для объявления target с типами контекстов, custom contexts и action scopes. + Также поддерживает альтернативную форму `defineTarget(id, contexts)`. ## Что такое `target` и `context` `target` — это идентификатор места встраивания виджета в интерфейсе CRM. Он отвечает на вопрос: -«куда CRM сейчас монтирует remote-виджет?». Например, `order/card:common.before` означает конкретную +«куда CRM сейчас монтирует встраиваемый виджет?». Например, `order/card:common.before` означает конкретную точку встраивания на карточке заказа. `context` — это набор реактивных данных, доступных виджету в этом месте. Он отвечает на вопрос: @@ -22,15 +24,6 @@ `target` не является данными заказа, клиента или пользователя. Это только место встраивания. Данные нужно брать из контекстов, которые привязаны к этому `target`. -## Примеры встроенных `target` - -| Target | Где встраивается | Доступные контексты | -| --- | --- | --- | -| `order/card:common.before` | Карточка заказа, перед блоком общей информации | `order/card`, `user/current`, `settings` | -| `order/card:customer.phone` | Карточка заказа, поле телефона клиента | `order/card`, `user/current`, `settings` | -| `customer/card:phone` | Карточка клиента, телефонный блок | `customer/card`, `customer/card:phone`, `user/current`, `settings` | -| `order/mg:list.before` | Карточка заказа, перед списком в multi-goods блоке | `order/card`, `order/card:settings`, `user/current`, `settings` | - ## Проверка контекстов для `target` ```ts @@ -60,6 +53,7 @@ const selectedTarget: TargetName = 'order/card:common.before' import type { TargetName } from '@retailcrm/embed-ui-v1-endpoint/common' import { useContext as useOrderContext } from '@retailcrm/embed-ui-v1-contexts/remote/order/card' +import { useContext as useOrderSettingsContext } from '@retailcrm/embed-ui-v1-contexts/remote/order/card-settings' import { useContext as useSettingsContext } from '@retailcrm/embed-ui-v1-contexts/remote/settings' import { useContext as useUserContext } from '@retailcrm/embed-ui-v1-contexts/remote/user/current' @@ -68,13 +62,14 @@ defineProps<{ }>() const order = useOrderContext() +const orderSettings = useOrderSettingsContext() const settings = useSettingsContext() const user = useUserContext() ``` Такой набор контекстов подходит для `order/card:common.before`, потому что этот `target` объявлен с -контекстами `order/card`, `user/current` и `settings`. +контекстами `order/card`, `order/card:settings`, `user/current` и `settings`. Для `customer/card:phone` набор импортов будет другим: @@ -85,18 +80,48 @@ import { useContext as useSettingsContext } from '@retailcrm/embed-ui-v1-context import { useContext as useUserContext } from '@retailcrm/embed-ui-v1-contexts/remote/user/current' ``` -## Пример `defineTarget` +## `defineTarget` в тестах + +CRM не предоставляет расширениям механизм регистрации произвольных widget targets. +В рабочем сценарии виджет монтируется только в заранее определённые платформой цели из `targets`. + +`defineTarget` нужен для объявления этих встроенных целей внутри пакета и для автотестов, +где требуется собрать изолированную target-конфигурацию без запуска CRM. ```ts import { defineTarget } from '@retailcrm/embed-ui-v1-endpoint/common' -const customTarget = defineTarget('order/card:custom.after', [ - 'order/card', +const testTarget = defineTarget('order/card:test.after', { + contexts: [ + 'order/card', + 'order/card:settings', + 'user/current', + 'settings', + ], + customContexts: ['order'], + actions: ['order/card'], +} as const) +``` + +Альтернативная форма с массивом контекстов подходит для target без custom contexts и action scopes. +В этом случае `customContexts` и `actions` будут пустыми: + +```ts +const testTarget = defineTarget('customer/card:test.after', [ + 'customer/card', 'user/current', 'settings', ] as const) ``` +## AI-friendly YAML profiles + +Для встроенных целей дополнительно генерируется каталог [`targets/*.yml`](./targets/). +Эти файлы предназначены для AI-ассистентов: они описывают target на английском, перечисляют +доступные contexts, custom contexts и action scopes, но не являются отдельным источником truth. +Обновляйте `targets.ts` и `targets.documentation.ts`, затем запускайте +`yarn workspace @retailcrm/embed-ui-v1-endpoint run build:docs`. + ## Практический совет Если раннер маппится по `target`, старайтесь использовать ключи из `TargetName`. @@ -104,8 +129,8 @@ const customTarget = defineTarget('order/card:custom.after', [ Читайте также: -- [`defineWidgetRunner`](./define-widget-runner.md) — как `target` попадает в remote-компонент. +- [`defineWidgetRunner`](./define-widget-runner.md) — как `target` попадает в компонент встраиваемого виджета. - [`menu-placements`](./menu-placements.md) — чем пункты меню для страниц отличаются от widget `target`. -- [`page-routes`](./page-routes.md) — как описывать page `code` и CRM route. +- [`page-routes`](./page-routes.md) — как описывать page `code` и CRM-маршрут. - [`CONCEPT`](../../v1-contexts/docs/ru/CONCEPT.md) — общий принцип работы контекстов. - [`CUSTOM`](../../v1-contexts/docs/ru/CUSTOM.md) — пользовательский контекст для custom fields. diff --git a/packages/v1-endpoint/package.json b/packages/v1-endpoint/package.json index 8d6d9947..ade89f30 100644 --- a/packages/v1-endpoint/package.json +++ b/packages/v1-endpoint/package.json @@ -1,5 +1,9 @@ { "name": "@retailcrm/embed-ui-v1-endpoint", + "bin": { + "embed-ui-v1-endpoint": "./bin/embed-ui-v1-endpoint.mjs", + "embed-ui-v1-endpoint-mcp": "./bin/embed-ui-v1-endpoint-mcp.mjs" + }, "type": "module", "version": "0.9.21", "description": "Endpoint API for integrations in RetailCRM", @@ -25,6 +29,12 @@ "require": "./dist/common/targets.cjs", "default": "./dist/common/targets.js" }, + "./mcp": { + "types": "./dist/mcp/server.d.ts", + "import": "./dist/mcp/server.js", + "require": "./dist/mcp/server.cjs", + "default": "./dist/mcp/server.js" + }, "./remote": { "types": "./dist/remote.d.ts", "import": "./dist/remote.js", @@ -54,6 +64,9 @@ "common/targets": [ "./dist/common/targets.d.ts" ], + "mcp": [ + "./dist/mcp/server.d.ts" + ], "remote": [ "./dist/remote.d.ts" ], @@ -66,18 +79,23 @@ } }, "files": [ + "bin", "dist", "docs", "README.md" ], "scripts": { - "build": "yarn build:code", + "build": "yarn build:docs && yarn build:code && yarn build:mcp && yarn build:meta", "build:code": "vite build -c ./vite.config.ts", + "build:docs": "npx tsx scripts/build.docs.ts", + "build:mcp": "vite build -c ./vite.config.mcp.ts", + "build:meta": "npx tsx scripts/build.meta.ts", "test:e2e": "yarn exec vitest --run --config ./vitest.config.playwright.ts", "test:playwright": "yarn exec vitest --run --config ./vitest.config.playwright.ts", "test": "vitest --run" }, "peerDependencies": { + "@omnicajs/vue-remote": "^0.2.23", "@remote-ui/rpc": "^1.4", "@retailcrm/embed-ui-v1-contexts": "^0.9.21", "@retailcrm/embed-ui-v1-types": "^0.9.21", @@ -85,6 +103,7 @@ "vue": "^3.5" }, "dependencies": { + "@modelcontextprotocol/sdk": "^1.29.0", "@remote-ui/rpc": "^1.4.7", "@retailcrm/embed-ui-v1-components": "^0.9.21", "@retailcrm/embed-ui-v1-contexts": "^0.9.21", @@ -97,6 +116,7 @@ "date-fns": "^4.1.0", "lodash.isequal": "^4.5.0", "playwright": "1.58.2", + "tsx": "^4.21.0", "vite": "^7.3.2", "vite-plugin-dts": "^4.5.4", "vitest": "4.1.3" diff --git a/packages/v1-endpoint/scripts/build.docs.ts b/packages/v1-endpoint/scripts/build.docs.ts new file mode 100644 index 00000000..2bc720fb --- /dev/null +++ b/packages/v1-endpoint/scripts/build.docs.ts @@ -0,0 +1,101 @@ +import type { TargetName } from '@/common/targets' + +import * as fs from 'node:fs' + +import { fileURLToPath } from 'node:url' + +import { dirname, join, resolve } from 'node:path' + +import { targets } from '@/common/targets' +import { targetsDocumentation } from '@/common/targets.documentation' + +const __dirname = dirname(fileURLToPath(import.meta.url)) + +const docs = resolve(__dirname, '../docs/targets/') + +const targetNames = Object.keys(targets) as TargetName[] + +const pageLabels: Record = { + 'customer/card': 'customer card', + 'order/card': 'full order form', + 'order/mg': 'chat order form', +} + +const quote = (value: string): string => JSON.stringify(value) + +const paragraph = (value: string): string => `>\n ${value}` + +const list = (values: readonly string[], indent = ' '): string => values.length === 0 + ? ' []' + : `\n${values.map(value => `${indent}- ${quote(value)}`).join('\n')}` + +const fileNameOf = (target: string): string => `${target.toLowerCase().replace(/[^a-z0-9]+/g, '-')}.yml` + +const pageOf = (target: string): string => target.split(':')[0] + +const areaOf = (target: string): string => target.split(':')[1] ?? '' + +const sentenceOf = (value: string): string => /[.!?]$/.test(value) ? value : `${value}.` + +const renderTarget = (target: TargetName): string => { + const config = targets[target] + const documentation = targetsDocumentation[target] + const page = pageOf(target) + const pageLabel = pageLabels[page] ?? page + const description = documentation.description['en-GB'] + const location = documentation.location['en-GB'] + + return `target: ${quote(target)} +summary: ${paragraph(`${sentenceOf(description)} It is placed in the ${pageLabel}: ${location}.`)} +language: en-GB +audience: ai + +public_import: + from: ${quote('@retailcrm/embed-ui-v1-endpoint/common')} + named: + - targets + - TargetName + +runner_import: + from: ${quote('@retailcrm/embed-ui-v1-endpoint/remote/widgets')} + named: + - defineWidgetRunner + - defineMultiRunner + +page: + id: ${quote(page)} + label: ${quote(pageLabel)} + area: ${quote(areaOf(target))} + +description: ${quote(description)} +location: ${quote(location)} + +target_config: + contexts:${list(config.contexts, ' ')} + custom_contexts:${list(config.customContexts, ' ')} + action_scopes:${list(config.actions, ' ')} + +use_when: + - ${quote(`Place a widget exactly at ${target}.`)} + - ${quote(`The widget belongs to the ${pageLabel} and should appear at this location: ${location}.`)} + - ${quote('The widget can work with the contexts listed in target_config.contexts.')} + +avoid_when: + - ${quote('The widget belongs to a different page, section, or field-level insertion point.')} + - ${quote('The widget requires contexts, custom contexts, or action scopes that are not listed in target_config.')} + +ai_notes: + - ${quote('Use the target id as the runner registration key.')} + - ${quote('Use targets[target].contexts as the source of truth for context availability.')} + - ${quote('Do not duplicate target context lists in generated widget code.')} +${target.startsWith('order/') + ? ` - ${quote('Order card and chat order form targets share the same order form data contract.')}\n` + : ''}` +} + +fs.rmSync(docs, { recursive: true, force: true }) +fs.mkdirSync(docs, { recursive: true }) + +for (const target of targetNames) { + fs.writeFileSync(join(docs, fileNameOf(target)), renderTarget(target)) +} diff --git a/packages/v1-endpoint/scripts/build.meta.ts b/packages/v1-endpoint/scripts/build.meta.ts new file mode 100644 index 00000000..0ac00c75 --- /dev/null +++ b/packages/v1-endpoint/scripts/build.meta.ts @@ -0,0 +1,27 @@ +import type { TargetName } from '@/common/targets' + +import * as fs from 'node:fs' + +import { fileURLToPath } from 'node:url' + +import { dirname, join, resolve } from 'node:path' + +import { targets } from '@/common/targets' +import { targetsDocumentation } from '@/common/targets.documentation' + +const __dirname = dirname(fileURLToPath(import.meta.url)) + +const dist = resolve(__dirname, '../dist/') + +if (!fs.existsSync(dist)) { + fs.mkdirSync(dist) +} + +const targetNames = Object.keys(targets) as TargetName[] + +fs.writeFileSync(join(dist, 'meta.json'), JSON.stringify({ + targets: targetNames.map(target => ({ + ...targets[target], + ...targetsDocumentation[target], + })), +}, null, 2)) diff --git a/packages/v1-endpoint/src/common/targets.documentation.ts b/packages/v1-endpoint/src/common/targets.documentation.ts new file mode 100644 index 00000000..9d7c1d33 --- /dev/null +++ b/packages/v1-endpoint/src/common/targets.documentation.ts @@ -0,0 +1,313 @@ +import type { TranslationList } from '@retailcrm/embed-ui-v1-types/doc' + +import type { TargetName } from './targets' + +type TargetDocumentation = { + [Target in TargetName]: { + description: TranslationList; + location: TranslationList; + } +} + +export const targetsDocumentation = { + 'customer/card:phone': { + description: { + 'en-GB': 'Widget for customer phone list item', + 'es-ES': 'Widget para el elemento de la lista de teléfonos del cliente', + 'ru-RU': 'Виджет для элемента списка телефонов клиента', + }, + location: { + 'en-GB': 'Right after the phone number in the list', + 'es-ES': 'Justo después del número de teléfono en la lista', + 'ru-RU': 'Сразу после номера телефона в списке', + }, + }, + 'customer/card:communications.after': { + description: { + 'en-GB': 'Widget for enhancing the communication section in the left column of the customer page.', + 'es-ES': 'Widget para ampliar la sección de comunicación en la columna izquierda de la página del cliente.', + 'ru-RU': 'Виджет для дополнения секции коммуникаций в левой колонке страницы клиента.', + }, + location: { + 'en-GB': 'Right below the short summary, in the communication section', + 'es-ES': 'Justo debajo del resumen breve, en la sección de comunicación', + 'ru-RU': 'Сразу под краткой сводкой, в секции коммуникаций', + }, + }, + 'customer/card:inWork.before': { + description: { + 'en-GB': 'Widget for the contact request item', + 'es-ES': 'Widget para el elemento de solicitud de contacto', + 'ru-RU': 'Виджет для элемента обращений', + }, + location: { + 'en-GB': 'At the beginning of the "In Progress" block in the client card', + 'es-ES': 'Al principio del bloque "En progreso" en la tarjeta del cliente', + 'ru-RU': 'В начале блока "В работе" в карточке клиента', + }, + }, + 'customer/card:inWork.after': { + description: { + 'en-GB': 'Widget for the contact request item', + 'es-ES': 'Widget para el elemento de solicitud de contacto', + 'ru-RU': 'Виджет для элемента обращений', + }, + location: { + 'en-GB': 'At the end of the "In progress" block in the client card', + 'es-ES': 'Al final del bloque "En progreso" en la tarjeta del cliente', + 'ru-RU': 'В конце блока "В работе" в карточке клиента', + }, + }, + 'order/card:common.before': { + description: { + 'en-GB': 'Widget for the section with common data', + 'es-ES': 'Widget para la sección con datos comunes', + 'ru-RU': 'Виджет для секции с основными данными', + }, + location: { + 'en-GB': 'Section start, right above the input fields', + 'es-ES': 'Inicio de la sección, justo encima de los campos de entrada', + 'ru-RU': 'Начало секции, над полями ввода', + }, + }, + 'order/card:common.after': { + description: { + 'en-GB': 'Widget for the section with common data', + 'es-ES': 'Widget para la sección con datos comunes', + 'ru-RU': 'Виджет для секции с основными данными', + }, + location: { + 'en-GB': 'Section end, right under the input fields', + 'es-ES': 'Fin de la sección, justo debajo de los campos de entrada', + 'ru-RU': 'Конец секции, под полями ввода', + }, + }, + 'order/card:customer.before': { + description: { + 'en-GB': 'Widget for the section with customer data', + 'es-ES': 'Widget para la sección con datos del cliente', + 'ru-RU': 'Виджет для секции с данными клиента', + }, + location: { + 'en-GB': 'Section start, right above the input fields', + 'es-ES': 'Inicio de la sección, justo encima de los campos de entrada', + 'ru-RU': 'Начало секции, над полями ввода', + }, + }, + 'order/card:customer.after': { + description: { + 'en-GB': 'Widget for the section with customer data', + 'es-ES': 'Widget para la sección con datos del cliente', + 'ru-RU': 'Виджет для секции с данными клиента', + }, + location: { + 'en-GB': 'Section end, right under the input fields', + 'es-ES': 'Fin de la sección, justo debajo de los campos de entrada', + 'ru-RU': 'Конец секции, под полями ввода', + }, + }, + 'order/card:customer.email': { + description: { + 'en-GB': 'Widget for customer email input field', + 'es-ES': 'Widget para el campo de entrada del correo electrónico del cliente', + 'ru-RU': 'Виджет для поля ввода email клиента', + }, + location: { + 'en-GB': 'Right after the input field', + 'es-ES': 'Justo después del campo de entrada', + 'ru-RU': 'Сразу после поля ввода', + }, + }, + 'order/card:customer.phone': { + description: { + 'en-GB': 'Widget for customer phone input field', + 'es-ES': 'Widget para el campo de entrada del teléfono del cliente', + 'ru-RU': 'Виджет для поля ввода телефона клиента', + }, + location: { + 'en-GB': 'Right after the input field', + 'es-ES': 'Justo después del campo de entrada', + 'ru-RU': 'Сразу после поля ввода', + }, + }, + 'order/card:list.before': { + description: { + 'en-GB': 'Widget for the list of ordered items', + 'es-ES': 'Widget para la lista de artículos pedidos', + 'ru-RU': 'Виджет для списка позиций заказа', + }, + location: { + 'en-GB': 'Section start, right above the input fields', + 'es-ES': 'Inicio de la sección, justo encima de los campos de entrada', + 'ru-RU': 'Начало секции, над полями ввода', + }, + }, + 'order/card:list.after': { + description: { + 'en-GB': 'Widget for the list of ordered items', + 'es-ES': 'Widget para la lista de artículos pedidos', + 'ru-RU': 'Виджет для списка позиций заказа', + }, + location: { + 'en-GB': 'Section start, right under the list', + 'es-ES': 'Inicio de la sección, justo debajo de la lista', + 'ru-RU': 'Начало секции, под списком', + }, + }, + 'order/card:store.before': { + description: { + 'en-GB': 'Widget for the section with warehouse data', + 'es-ES': 'Widget para la sección con datos del almacén', + 'ru-RU': 'Виджет для секции с данными склада', + }, + location: { + 'en-GB': 'Section start, right above the input fields', + 'es-ES': 'Inicio de la sección, justo encima de los campos de entrada', + 'ru-RU': 'Начало секции, над полями ввода', + }, + }, + 'order/card:dimensions.before': { + description: { + 'en-GB': 'Widget for the section with dimensions and weight', + 'es-ES': 'Widget para la sección con dimensiones y peso', + 'ru-RU': 'Виджет для секции с данными габаритов и веса', + }, + location: { + 'en-GB': 'Section start, right above the input fields', + 'es-ES': 'Inicio de la sección, justo encima de los campos de entrada', + 'ru-RU': 'Начало секции, над полями ввода', + }, + }, + 'order/card:delivery.before': { + description: { + 'en-GB': 'Widget for the section with delivery data', + 'es-ES': 'Widget para la sección con datos de entrega', + 'ru-RU': 'Виджет для секции с данными доставки', + }, + location: { + 'en-GB': 'Section start, right above the input fields', + 'es-ES': 'Inicio de la sección, justo encima de los campos de entrada', + 'ru-RU': 'Начало секции, над полями ввода', + }, + }, + 'order/card:delivery.after': { + description: { + 'en-GB': 'Widget for the section with delivery data', + 'es-ES': 'Widget para la sección con datos de entrega', + 'ru-RU': 'Виджет для секции с данными доставки', + }, + location: { + 'en-GB': 'Section end, right under the input fields', + 'es-ES': 'Fin de la sección, justo debajo de los campos de entrada', + 'ru-RU': 'Конец секции, под полями ввода', + }, + }, + 'order/card:delivery.address': { + description: { + 'en-GB': 'Widget for delivery address input field', + 'es-ES': 'Widget para el campo de entrada de la dirección de entrega', + 'ru-RU': 'Виджет для поля ввода адреса доставки', + }, + location: { + 'en-GB': 'Right under the input field', + 'es-ES': 'Justo debajo del campo de entrada', + 'ru-RU': 'Под полем ввода адреса', + }, + }, + 'order/card:payment.before': { + description: { + 'en-GB': 'Widget for the section with payment data', + 'es-ES': 'Widget para la sección con datos de pago', + 'ru-RU': 'Виджет для секции с данными по оплате', + }, + location: { + 'en-GB': 'Section start, right above the input fields', + 'es-ES': 'Inicio de la sección, justo encima de los campos de entrada', + 'ru-RU': 'Начало секции, над полями ввода', + }, + }, + 'order/card:comment.manager.before': { + description: { + 'en-GB': 'Widget for the block "Manager comment"', + 'es-ES': 'Widget para el bloque "Comentario del asesor"', + 'ru-RU': 'Виджет для блока "Комментарии оператора"', + }, + location: { + 'en-GB': 'Section start, right above the input field', + 'es-ES': 'Inicio de la sección, justo encima del campo de entrada', + 'ru-RU': 'Начало секции, над полем ввода', + }, + }, + 'order/mg:list.before': { + description: { + 'en-GB': 'Widget for the block "Order items"', + 'es-ES': 'Widget para el bloque "Artículos del pedido"', + 'ru-RU': 'Виджет для блока "Состав заказа"', + }, + location: { + 'en-GB': 'Section start, right above the list of order items', + 'es-ES': 'Inicio de la sección, justo encima de la lista de artículos del pedido', + 'ru-RU': 'Начало секции, над списком товарных позиций', + }, + }, + 'order/mg:list.after': { + description: { + 'en-GB': 'Widget for the block "Order items"', + 'es-ES': 'Widget para el bloque "Artículos del pedido"', + 'ru-RU': 'Виджет для блока "Состав заказа"', + }, + location: { + 'en-GB': 'Section end, right after the list of order items and before the discount, privilege selection, etc. input fields', + 'es-ES': 'Fin de la sección, justo después de la lista de artículos del pedido y antes de los campos de entrada de descuento, selección de privilegios, etc.', + 'ru-RU': 'Конец секции, сразу после списка товарных позиций и до полей ввода скидки, выбора привилегии и т.п.', + }, + }, + 'order/mg:delivery.before': { + description: { + 'en-GB': 'Widget for the block "Delivery"', + 'es-ES': 'Widget para el bloque "Entrega"', + 'ru-RU': 'Виджет для блока "Доставка"', + }, + location: { + 'en-GB': 'Section start, right above the input field', + 'es-ES': 'Inicio de la sección, justo encima del campo de entrada', + 'ru-RU': 'Начало секции, над полем ввода', + }, + }, + 'order/mg:delivery.after': { + description: { + 'en-GB': 'Widget for the block "Delivery"', + 'es-ES': 'Widget para el bloque "Entrega"', + 'ru-RU': 'Виджет для блока "Доставка"', + }, + location: { + 'en-GB': 'Section end, right under the input fields', + 'es-ES': 'Fin de la sección, justo debajo de los campos de entrada', + 'ru-RU': 'Конец секции, под полями ввода', + }, + }, + 'order/mg:payment.before': { + description: { + 'en-GB': 'Widget for the block "Payment"', + 'es-ES': 'Widget para el bloque "Pago"', + 'ru-RU': 'Виджет для блока "Оплата"', + }, + location: { + 'en-GB': 'Section start, right above the input field', + 'es-ES': 'Inicio de la sección, justo encima del campo de entrada', + 'ru-RU': 'Начало секции, над полем ввода', + }, + }, + 'order/mg:payment.after': { + description: { + 'en-GB': 'Widget for the block "Payment"', + 'es-ES': 'Widget para el bloque "Pago"', + 'ru-RU': 'Виджет для блока "Оплата"', + }, + location: { + 'en-GB': 'Section end, after the list of payments, controls, and custom fields', + 'es-ES': 'Fin de la sección, después de la lista de pagos, controles y campos personalizados', + 'ru-RU': 'Конец секции, после списка оплат, контролов и пользовательских полей', + }, + }, +} satisfies TargetDocumentation diff --git a/packages/v1-endpoint/src/common/targets.ts b/packages/v1-endpoint/src/common/targets.ts index 535194bf..ab613230 100644 --- a/packages/v1-endpoint/src/common/targets.ts +++ b/packages/v1-endpoint/src/common/targets.ts @@ -3,176 +3,127 @@ import type { SchemaList } from '@retailcrm/embed-ui-v1-contexts/types' export type TargetDefinition< TId extends string = string, TContexts extends readonly (keyof SchemaList)[] = readonly (keyof SchemaList)[], + TCustomContexts extends readonly string[] = readonly string[], + TActions extends readonly string[] = readonly string[], > = { id: TId; contexts: TContexts; + customContexts: TCustomContexts; + actions: TActions; } -export const defineTarget = < - const TId extends string, - const TContexts extends readonly (keyof SchemaList)[], ->(id: TId, contexts: TContexts): TargetDefinition => ({ - id, - contexts, - }) +export type TargetConfig< + TContexts extends readonly (keyof SchemaList)[] = readonly (keyof SchemaList)[], + TCustomContexts extends readonly string[] = readonly string[], + TActions extends readonly string[] = readonly string[], +> = { + contexts: TContexts; + customContexts: TCustomContexts; + actions: TActions; +} -export const targets = { - 'customer/card:phone': defineTarget('customer/card:phone', [ - 'customer/card', - 'customer/card:phone', - 'user/current', - 'settings', - ]), +const isTargetConfig = ( + configOrContexts: readonly (keyof SchemaList)[] | TargetConfig +): configOrContexts is TargetConfig => !Array.isArray(configOrContexts) - 'customer/card:communications.after': defineTarget('customer/card:communications.after', [ - 'customer/card', - 'user/current', - 'settings', - ]), +export function defineTarget< + const TId extends string, + const TContexts extends readonly (keyof SchemaList)[], +>( + id: TId, + contexts: TContexts +): TargetDefinition - 'customer/card:inWork.before': defineTarget('customer/card:inWork.before', [ - 'customer/card', - 'user/current', - 'settings', - ]), +export function defineTarget< + const TId extends string, + const TContexts extends readonly (keyof SchemaList)[], + const TCustomContexts extends readonly string[], + const TActions extends readonly string[], +>( + id: TId, + config: TargetConfig +): TargetDefinition + +export function defineTarget( + id: string, + configOrContexts: + | readonly (keyof SchemaList)[] + | TargetConfig +): TargetDefinition { + if (isTargetConfig(configOrContexts)) { + return { + id, + ...configOrContexts, + } + } + + return { + id, + contexts: configOrContexts, + customContexts: [], + actions: [], + } +} - 'customer/card:inWork.after': defineTarget('customer/card:inWork.after', [ +const customerCardTarget = { + contexts: [ 'customer/card', 'user/current', 'settings', - ]), - - 'order/card:common.before': defineTarget('order/card:common.before', [ - 'order/card', - 'user/current', - 'settings', - ]), - - 'order/card:common.after': defineTarget('order/card:common.after', [ - 'order/card', - 'user/current', - 'settings', - ]), - - 'order/card:customer.before': defineTarget('order/card:customer.before', [ - 'order/card', - 'user/current', - 'settings', - ]), - - 'order/card:customer.after': defineTarget('order/card:customer.after', [ - 'order/card', - 'user/current', - 'settings', - ]), - - 'order/card:customer.email': defineTarget('order/card:customer.email', [ - 'order/card', - 'user/current', - 'settings', - ]), - - 'order/card:customer.phone': defineTarget('order/card:customer.phone', [ - 'order/card', - 'user/current', - 'settings', - ]), - - 'order/card:list.before': defineTarget('order/card:list.before', [ - 'order/card', - 'user/current', - 'settings', - ]), - - 'order/card:list.after': defineTarget('order/card:list.after', [ - 'order/card', - 'user/current', - 'settings', - ]), - - 'order/card:store.before': defineTarget('order/card:store.before', [ - 'order/card', - 'user/current', - 'settings', - ]), - - 'order/card:dimensions.before': defineTarget('order/card:dimensions.before', [ - 'order/card', - 'user/current', - 'settings', - ]), - - 'order/card:delivery.before': defineTarget('order/card:delivery.before', [ - 'order/card', - 'user/current', - 'settings', - ]), - - 'order/card:delivery.after': defineTarget('order/card:delivery.after', [ - 'order/card', - 'user/current', - 'settings', - ]), - - 'order/card:delivery.address': defineTarget('order/card:delivery.address', [ - 'order/card', - 'user/current', - 'settings', - ]), - - 'order/card:payment.before': defineTarget('order/card:payment.before', [ - 'order/card', - 'user/current', - 'settings', - ]), - - 'order/card:comment.manager.before': defineTarget('order/card:comment.manager.before', [ - 'order/card', - 'user/current', - 'settings', - ]), - - 'order/mg:list.before': defineTarget('order/mg:list.before', [ - 'order/card', - 'order/card:settings', - 'user/current', - 'settings', - ]), - - 'order/mg:list.after': defineTarget('order/mg:list.after', [ - 'order/card', - 'order/card:settings', - 'user/current', - 'settings', - ]), - - 'order/mg:delivery.before': defineTarget('order/mg:delivery.before', [ - 'order/card', - 'order/card:settings', - 'user/current', - 'settings', - ]), - - 'order/mg:delivery.after': defineTarget('order/mg:delivery.after', [ - 'order/card', - 'order/card:settings', - 'user/current', - 'settings', - ]), + ], + customContexts: ['customer'], + actions: [], +} as const - 'order/mg:payment.before': defineTarget('order/mg:payment.before', [ +const orderFormTarget = { + contexts: [ 'order/card', 'order/card:settings', 'user/current', 'settings', - ]), + ], + customContexts: ['order'], + actions: ['order/card'], +} as const - 'order/mg:payment.after': defineTarget('order/mg:payment.after', [ - 'order/card', - 'order/card:settings', - 'user/current', - 'settings', - ]), +export const targets = { + 'customer/card:phone': defineTarget('customer/card:phone', { + ...customerCardTarget, + contexts: [ + 'customer/card', + 'customer/card:phone', + 'user/current', + 'settings', + ], + }), + 'customer/card:communications.after': defineTarget('customer/card:communications.after', customerCardTarget), + 'customer/card:inWork.before': defineTarget('customer/card:inWork.before', customerCardTarget), + 'customer/card:inWork.after': defineTarget('customer/card:inWork.after', customerCardTarget), + 'order/card:common.before': defineTarget('order/card:common.before', orderFormTarget), + 'order/card:common.after': defineTarget('order/card:common.after', orderFormTarget), + 'order/card:customer.before': defineTarget('order/card:customer.before', orderFormTarget), + 'order/card:customer.after': defineTarget('order/card:customer.after', orderFormTarget), + 'order/card:customer.email': defineTarget('order/card:customer.email', orderFormTarget), + 'order/card:customer.phone': defineTarget('order/card:customer.phone', orderFormTarget), + 'order/card:list.before': defineTarget('order/card:list.before', orderFormTarget), + 'order/card:list.after': defineTarget('order/card:list.after', orderFormTarget), + 'order/card:store.before': defineTarget('order/card:store.before', orderFormTarget), + 'order/card:dimensions.before': defineTarget('order/card:dimensions.before', orderFormTarget), + 'order/card:delivery.before': defineTarget('order/card:delivery.before', orderFormTarget), + 'order/card:delivery.after': defineTarget('order/card:delivery.after', orderFormTarget), + 'order/card:delivery.address': defineTarget('order/card:delivery.address', orderFormTarget), + 'order/card:payment.before': defineTarget('order/card:payment.before', orderFormTarget), + 'order/card:comment.manager.before': defineTarget('order/card:comment.manager.before', orderFormTarget), + 'order/mg:list.before': defineTarget('order/mg:list.before', orderFormTarget), + 'order/mg:list.after': defineTarget('order/mg:list.after', orderFormTarget), + 'order/mg:delivery.before': defineTarget('order/mg:delivery.before', orderFormTarget), + 'order/mg:delivery.after': defineTarget('order/mg:delivery.after', orderFormTarget), + 'order/mg:payment.before': defineTarget('order/mg:payment.before', orderFormTarget), + 'order/mg:payment.after': defineTarget('order/mg:payment.after', orderFormTarget), } as const export type TargetName = keyof typeof targets + +export type TargetList = { + [Target in TargetName]: Pick +} diff --git a/packages/v1-endpoint/src/mcp/server.ts b/packages/v1-endpoint/src/mcp/server.ts new file mode 100644 index 00000000..c9814e81 --- /dev/null +++ b/packages/v1-endpoint/src/mcp/server.ts @@ -0,0 +1,127 @@ +import * as fs from 'node:fs' + +import process from 'node:process' + +import { fileURLToPath } from 'node:url' + +import { dirname, join, resolve } from 'node:path' + +import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js' +import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js' + +const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..') +const targetDocs = join(packageRoot, 'docs/targets') +const packageJson = join(packageRoot, 'package.json') + +type TargetProfile = { + id: string; + file: string; + uri: string; + content: string; +} + +const targetUri = (target: string): string => + `embed-ui-v1-endpoint://targets/${encodeURIComponent(target)}` + +const readPackageVersion = (): string => { + const content = fs.readFileSync(packageJson, 'utf8') + + return JSON.parse(content).version +} + +const readTargetProfiles = (): TargetProfile[] => { + if (!fs.existsSync(targetDocs)) { + return [] + } + + return fs.readdirSync(targetDocs) + .filter(file => file.endsWith('.yml')) + .sort() + .map(file => { + const content = fs.readFileSync(join(targetDocs, file), 'utf8') + const target = content.match(/^target: "(.+)"$/m)?.[1] + + if (!target) { + throw new Error(`Target profile ${file} does not contain target field`) + } + + return { + id: target, + file, + uri: targetUri(target), + content, + } + }) +} + +const waitForCloseSignal = (): Promise => { + const keepAlive = setInterval(() => undefined, 2 ** 31 - 1) + + process.stdin.resume() + + return new Promise(resolve => { + const close = (): void => { + clearInterval(keepAlive) + resolve() + } + + process.once('SIGINT', close) + process.once('SIGTERM', close) + }) +} + +export const createEndpointMcpServer = (): McpServer => { + const server = new McpServer({ + name: '@retailcrm/embed-ui-v1-endpoint', + version: readPackageVersion(), + }) + + const targets = readTargetProfiles() + + server.registerResource('v1-endpoint targets index', 'embed-ui-v1-endpoint://targets', { + title: 'v1-endpoint widget targets index', + description: 'Machine-readable index of built-in widget targets provided by @retailcrm/embed-ui-v1-endpoint.', + mimeType: 'application/json', + }, uri => ({ + contents: [{ + uri: uri.href, + mimeType: 'application/json', + text: JSON.stringify({ + package: '@retailcrm/embed-ui-v1-endpoint', + resources: targets.map(target => ({ + target: target.id, + uri: target.uri, + file: `docs/targets/${target.file}`, + })), + }, null, 2), + }], + })) + + for (const target of targets) { + server.registerResource(`v1-endpoint target ${target.id}`, target.uri, { + title: `Target ${target.id}`, + description: `AI-friendly YAML profile for widget target ${target.id}.`, + mimeType: 'application/yaml', + annotations: { + audience: ['assistant'], + priority: 0.8, + }, + }, uri => ({ + contents: [{ + uri: uri.href, + mimeType: 'application/yaml', + text: target.content, + }], + })) + } + + return server +} + +export const runEndpointMcpServer = async (): Promise => { + const server = createEndpointMcpServer() + + await server.connect(new StdioServerTransport()) + await waitForCloseSignal() + await server.close() +} diff --git a/packages/v1-endpoint/tests/factories/targets.test.ts b/packages/v1-endpoint/tests/factories/targets.test.ts index 54d7febc..c98aacaa 100644 --- a/packages/v1-endpoint/tests/factories/targets.test.ts +++ b/packages/v1-endpoint/tests/factories/targets.test.ts @@ -7,4 +7,19 @@ test('defineTarget returns typed target shape', () => { expect(target.id).toBe('order/card:common.before') expect(target.contexts).toEqual(['order/card', 'user/current', 'settings']) + expect(target.customContexts).toEqual([]) + expect(target.actions).toEqual([]) +}) + +test('defineTarget accepts target config shape', () => { + const target = defineTarget('order/card:common.before', { + contexts: ['order/card', 'order/card:settings', 'user/current', 'settings'] as const, + customContexts: ['order'] as const, + actions: ['order/card'] as const, + }) + + expect(target.id).toBe('order/card:common.before') + expect(target.contexts).toEqual(['order/card', 'order/card:settings', 'user/current', 'settings']) + expect(target.customContexts).toEqual(['order']) + expect(target.actions).toEqual(['order/card']) }) diff --git a/packages/v1-endpoint/tsconfig.json b/packages/v1-endpoint/tsconfig.json index 4f9578bd..c8dec5b2 100644 --- a/packages/v1-endpoint/tsconfig.json +++ b/packages/v1-endpoint/tsconfig.json @@ -32,6 +32,7 @@ "useDefineForClassFields": true }, "include": [ + "scripts/**/*.ts", "src/**/*.ts" ] } diff --git a/packages/v1-endpoint/vite.config.mcp.ts b/packages/v1-endpoint/vite.config.mcp.ts new file mode 100644 index 00000000..a5ac4534 --- /dev/null +++ b/packages/v1-endpoint/vite.config.mcp.ts @@ -0,0 +1,55 @@ +import { builtinModules } from 'node:module' +import * as path from 'node:path' + +import { defineConfig } from 'vite' +import dts from 'vite-plugin-dts' + +import { dependencies, peerDependencies } from './package.json' + +const externalPackages = [ + ...Object.keys(peerDependencies ?? {}), + ...Object.keys(dependencies ?? {}), +] + +const builtinPackageNames = new Set([ + ...builtinModules, + ...builtinModules.map(module => `node:${module}`), +]) + +const isPackageExternal = (id: string): boolean => + builtinPackageNames.has(id) + || externalPackages.some(packageName => id === packageName || id.startsWith(`${packageName}/`)) + +export default defineConfig({ + plugins: [dts({ + tsconfigPath: path.resolve(__dirname, './tsconfig.json'), + entryRoot: path.resolve(__dirname, './src/mcp'), + include: [path.resolve(__dirname, './src/mcp')], + outDir: path.resolve(__dirname, './dist/mcp'), + insertTypesEntry: false, + staticImport: true, + })], + build: { + emptyOutDir: false, + lib: { + entry: { + server: path.resolve(__dirname, './src/mcp/server.ts'), + }, + formats: ['es', 'cjs'], + fileName: (format, name) => `${name}.${{ + es: 'js', + cjs: 'cjs', + }[format as 'es' | 'cjs']}`, + }, + rollupOptions: { + external: isPackageExternal, + output: { + exports: 'named', + dir: path.join(__dirname, '/dist/mcp'), + }, + }, + minify: false, + ssr: true, + target: 'node22', + }, +}) diff --git a/scripts/build.meta.ts b/scripts/build.meta.ts index d0837ec1..ad97b41d 100644 --- a/scripts/build.meta.ts +++ b/scripts/build.meta.ts @@ -5,10 +5,9 @@ import { fileURLToPath } from 'node:url' import { dirname, join, resolve } from 'node:path' import basic from '@retailcrm/embed-ui-v1-contexts/dist/meta.json' +import endpoint from '@retailcrm/embed-ui-v1-endpoint/dist/meta.json' -import { pageListDocumentation, targetListDocumentation } from '~meta' - -import { keysOf } from '@/utilities' +import { pageListDocumentation } from '~meta' const __dirname = dirname(fileURLToPath(import.meta.url)) @@ -20,9 +19,11 @@ if (!fs.existsSync(dist)) { fs.writeFileSync(join(dist, 'meta.json'), JSON.stringify({ ...basic, - targets: keysOf(targetListDocumentation).map(target => ({ - id: target, - ...targetListDocumentation[target], + targets: endpoint.targets, + pages: pageListDocumentation.map(page => ({ + ...page, + targets: endpoint.targets + .map(target => target.id) + .filter(target => target.startsWith(`${page.id}:`)), })), - pages: pageListDocumentation, }, null, 2)) diff --git a/src/cmd/embed-ui/agents.ts b/src/cmd/embed-ui/agents.ts new file mode 100644 index 00000000..817f0805 --- /dev/null +++ b/src/cmd/embed-ui/agents.ts @@ -0,0 +1,128 @@ +import type { InitChanges } from './types' +import type { InitOptions } from './args' +import type { InstallablePackage, InstallablePackageHook } from './types' +import type { PackageManager } from './args' + +import fs from 'node:fs' +import path from 'node:path' + +import { DEFAULT_NEWLINE } from './package-json' +import { runPackageHookCommand } from './package-hook-runner' + +const ROOT_AGENTS_SECTION_HEADER = '## @retailcrm/embed-ui' + +const createRootAgentsSection = (): string => `${ROOT_AGENTS_SECTION_HEADER} + +When working with RetailCRM embedded UI in this project: + +1. Use documented public package entrypoints instead of package internals. +2. Read package README files from \`./node_modules/@retailcrm/embed-ui*\` before changing integration code. +3. Prefer package-provided \`AGENTS.md\`, MCP resources, YAML profiles, and docs over guessing from source names. +4. Keep widget targets, page codes, contexts, and host API contracts aligned with package documentation. +` + +const appendOrReplaceSection = ( + content: string, + header: string, + section: string, + force: boolean +): string | null => { + const escapedHeader = header.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + const sectionPattern = new RegExp(`${escapedHeader}[\\s\\S]*?(?=\\n##\\s|$)`, 'u') + + if (sectionPattern.test(content)) { + if (!force) { + return null + } + + return content.replace(sectionPattern, section.trimEnd()).replace(/\s+$/u, '') + DEFAULT_NEWLINE + } + + const trimmed = content.replace(/\s+$/u, '') + + return `${trimmed}${trimmed ? `${DEFAULT_NEWLINE}${DEFAULT_NEWLINE}` : ''}${section}${DEFAULT_NEWLINE}` +} + +const updateRootAgents = (cwd: string, options: InitOptions, changes: InitChanges): void => { + const agentsPath = path.join(cwd, 'AGENTS.md') + const section = createRootAgentsSection() + const content = fs.existsSync(agentsPath) + ? fs.readFileSync(agentsPath, 'utf8') + : '# AGENTS.md\n' + const nextContent = appendOrReplaceSection(content, ROOT_AGENTS_SECTION_HEADER, section, options.force || options.forceAgents) + + if (nextContent === null) { + changes.skipped.push(`${agentsPath} already contains ${ROOT_AGENTS_SECTION_HEADER}`) + return + } + + if (!options.dryRun) { + fs.writeFileSync(agentsPath, nextContent, 'utf8') + } + + changes.agents.push(`update ${agentsPath}`) +} + +const runInitAgentsHook = ( + packageName: string, + binName: string, + cwd: string, + packageManager: PackageManager, + failureMode: InstallablePackageHook['failureMode'], + options: InitOptions, + changes: InitChanges +): void => { + const args: string[] = ['init-agents', cwd] + + if (options.force || options.forceAgents) { + args.push('--force') + } + + runPackageHookCommand( + cwd, + packageName, + binName, + packageManager, + args, + failureMode, + options, + changes + ) +} + +export const applyInitAgents = ( + cwd: string, + selectedPackages: InstallablePackage[], + packageManager: PackageManager, + options: InitOptions, + changes: InitChanges +): void => { + if (options.noAgents) { + return + } + + updateRootAgents(cwd, options, changes) + + for (const selectedPackage of selectedPackages) { + for (const hook of selectedPackage.hooks ?? []) { + if (hook.type !== 'agents') { + continue + } + + if (hook.requiresMcp && options.noMcp) { + changes.warnings.push(`Skipping ${selectedPackage.id} ${hook.command} because it currently includes MCP instructions`) + continue + } + + runInitAgentsHook( + selectedPackage.name, + hook.binName, + cwd, + packageManager, + hook.failureMode, + options, + changes + ) + } + } +} diff --git a/src/cmd/embed-ui/args.ts b/src/cmd/embed-ui/args.ts new file mode 100644 index 00000000..60d6f629 --- /dev/null +++ b/src/cmd/embed-ui/args.ts @@ -0,0 +1,318 @@ +import path from 'node:path' +import process from 'node:process' + +import yargs from 'yargs' + +export const PACKAGE_MANAGERS = ['yarn', 'npm', 'pnpm', 'bun'] as const + +export type PackageManager = typeof PACKAGE_MANAGERS[number] + +export interface UpdateOptions { + command: 'update'; + target: string; + version: string | null; + dryRun: boolean; + exact: boolean; + add: boolean; + packages: string[] | null; +} + +export interface InitOptions { + command: 'init'; + cwd: string; + target: string | null; + version: string | null; + dryRun: boolean; + exact: boolean; + packages: string[] | null; + with: string[] | null; + packageManager: PackageManager | null; + noInstall: boolean; + force: boolean; + forceDeps: boolean; + fixSections: boolean; + forceFiles: boolean; + noDirs: boolean; + dirs: string[] | null; + srcDir: string | null; + noTemplate: boolean; + template: string; + pageCode: string; + widgetTarget: string; + noAgents: boolean; + forceAgents: boolean; + agentsOnly: boolean; + noMcp: boolean; + forceMcp: boolean; + mcpClientConfigs: string[] | null; +} + +export type CliOptions = InitOptions | UpdateOptions + +export const HELP_TEXT = `Usage: + npx @retailcrm/embed-ui [target] [version] [options] + npx @retailcrm/embed-ui init [target] [options] + +Options: + -t, --target Target path (default: current directory) + -v, --version Target version. If omitted, latest npm version is used + --exact Use exact version instead of range + --dry-run Show changes without writing package.json + --add Add selected embed-ui packages into one package.json + --packages Comma-separated package ids or names for --add/init + --cwd Project working directory for init + --package-manager Package manager for init installs + --no-install Do not run package manager install in init mode + --force-deps Replace incompatible existing init dependencies + --fix-sections Move init dependencies to expected package.json sections + --no-agents Do not create or update AGENTS.md in init mode + --no-mcp Do not add package MCP instructions in init mode + --mcp-client-configs Comma-separated MCP client configs to create (cursor,junie,vscode) + -h, --help Show this help + +Examples: + npx @retailcrm/embed-ui + npx @retailcrm/embed-ui --version 0.9.11 + npx @retailcrm/embed-ui ./my-project 0.9.11 + npx @retailcrm/embed-ui --target ./my-project --dry-run + npx @retailcrm/embed-ui --add + npx @retailcrm/embed-ui --add --packages components,contexts + npx @retailcrm/embed-ui init ./web --package-manager yarn +` + +const isSemverLike = (value: string): boolean => /^v?\d+\.\d+\.\d+/.test(value) +const stripLeadingV = (value: string): string => value.replace(/^v/, '') + +export const parsePackageList = (value: string): string[] => + value + .split(',') + .map((entry) => entry.trim()) + .filter(Boolean) + +export const parseInitArgs = (argv: string[]): InitOptions => { + const normalizedArgv = argv.map((argument) => { + if (argument === '--no-dirs') { + return '--no-dirs-enabled' + } + + if (argument === '--no-template') { + return '--no-template-enabled' + } + + return argument + }) + const parsed = yargs(normalizedArgv) + .scriptName('embed-ui') + .usage('Usage: $0 init [target] [options]') + .help(false) + .version(false) + .exitProcess(false) + .strictOptions() + .parserConfiguration({ + 'camel-case-expansion': true, + 'boolean-negation': true, + }) + .option('cwd', { + type: 'string', + default: process.cwd(), + describe: 'Project working directory', + }) + .option('help', { + alias: 'h', + type: 'boolean', + }) + .option('target', { + alias: 't', + type: 'string', + describe: 'Frontend target directory relative to cwd', + }) + .option('version', { + alias: 'v', + type: 'string', + coerce: stripLeadingV, + describe: 'Target package version', + }) + .option('packages', { + type: 'string', + coerce: parsePackageList, + describe: 'Comma-separated init package ids or names', + }) + .option('with', { + type: 'string', + coerce: parsePackageList, + describe: 'Additional published package ids or names', + }) + .option('package-manager', { + type: 'string', + choices: PACKAGE_MANAGERS, + describe: 'Package manager used for install', + }) + .option('dirs', { + type: 'string', + coerce: parsePackageList, + describe: 'Comma-separated directory presets', + }) + .option('src-dir', { + type: 'string', + describe: 'Frontend source root relative to cwd', + }) + .option('template', { + type: 'string', + default: 'order-card', + describe: 'Starter template name', + }) + .option('page-code', { + type: 'string', + default: 'settings', + describe: 'Starter embedded page code', + }) + .option('widget-target', { + type: 'string', + default: 'order/card:common.after', + describe: 'Starter widget target', + }) + .option('dry-run', { type: 'boolean', default: false }) + .option('exact', { type: 'boolean', default: false }) + .option('install', { type: 'boolean', default: true }) + .option('force', { type: 'boolean', default: false }) + .option('force-deps', { type: 'boolean', default: false }) + .option('fix-sections', { type: 'boolean', default: false }) + .option('force-files', { type: 'boolean', default: false }) + .option('dirs-enabled', { type: 'boolean', default: true }) + .option('template-enabled', { type: 'boolean', default: true }) + .option('agents', { type: 'boolean', default: true }) + .option('force-agents', { type: 'boolean', default: false }) + .option('agents-only', { type: 'boolean', default: false }) + .option('mcp', { type: 'boolean', default: true }) + .option('force-mcp', { type: 'boolean', default: false }) + .option('mcp-client-configs', { + type: 'string', + coerce: parsePackageList, + describe: 'Comma-separated MCP client config ids', + }) + .parseSync() + + if (parsed.help || parsed.h) { + console.log(HELP_TEXT) + process.exit(0) + } + + const positionals = parsed._.map(String) + if (positionals.length > 1) { + throw new Error('Too many positional arguments') + } + + if (!parsed.mcp && parsed.mcpClientConfigs?.length) { + throw new Error('Option --mcp-client-configs cannot be used together with --no-mcp') + } + + return { + command: 'init', + cwd: path.resolve(process.cwd(), parsed.cwd), + target: parsed.target ?? positionals[0] ?? null, + version: parsed.version ?? null, + dryRun: parsed.dryRun, + exact: parsed.exact, + packages: parsed.packages ?? null, + with: parsed.with ?? null, + packageManager: parsed.packageManager ?? null, + noInstall: !parsed.install, + force: parsed.force, + forceDeps: parsed.forceDeps, + fixSections: parsed.fixSections, + forceFiles: parsed.forceFiles, + noDirs: !parsed.dirsEnabled, + dirs: parsed.dirs ?? null, + srcDir: parsed.srcDir ?? null, + noTemplate: !parsed.templateEnabled, + template: parsed.template, + pageCode: parsed.pageCode, + widgetTarget: parsed.widgetTarget, + noAgents: !parsed.agents, + forceAgents: parsed.forceAgents, + agentsOnly: parsed.agentsOnly, + noMcp: !parsed.mcp, + forceMcp: parsed.forceMcp, + mcpClientConfigs: parsed.mcpClientConfigs ?? null, + } +} + +export const parseArgs = (argv: string[]): CliOptions => { + if (argv[0] === 'init') { + return parseInitArgs(argv.slice(1)) + } + + const parsed = yargs(argv) + .scriptName('embed-ui') + .usage('Usage: $0 [target] [version] [options]') + .help(false) + .version(false) + .exitProcess(false) + .strictOptions() + .option('target', { + alias: 't', + type: 'string', + default: process.cwd(), + }) + .option('help', { + alias: 'h', + type: 'boolean', + }) + .option('version', { + alias: 'v', + type: 'string', + coerce: stripLeadingV, + }) + .option('dry-run', { type: 'boolean', default: false }) + .option('exact', { type: 'boolean', default: false }) + .option('add', { type: 'boolean', default: false }) + .option('packages', { + type: 'string', + coerce: parsePackageList, + }) + .parseSync() + + if (parsed.help || parsed.h) { + console.log(HELP_TEXT) + process.exit(0) + } + + const positionals = parsed._.map(String) + + if (positionals.length > 2) { + throw new Error('Too many positional arguments') + } + + const options: UpdateOptions = { + command: 'update', + target: path.resolve(process.cwd(), parsed.target), + version: parsed.version ?? null, + dryRun: parsed.dryRun, + exact: parsed.exact, + add: parsed.add, + packages: parsed.packages ?? null, + } + + if (positionals.length >= 1) { + const first = positionals[0] + if (!options.version && isSemverLike(first)) { + options.version = stripLeadingV(first) + } else { + options.target = path.resolve(process.cwd(), first) + } + } + + if (positionals.length === 2) { + if (options.version) { + throw new Error('Version is already specified') + } + + options.version = stripLeadingV(positionals[1]) + } + + if (options.packages && !options.add) { + throw new Error('Option --packages can only be used together with --add') + } + + return options +} diff --git a/src/cmd/embed-ui/filesystem.ts b/src/cmd/embed-ui/filesystem.ts new file mode 100644 index 00000000..11b9e4b0 --- /dev/null +++ b/src/cmd/embed-ui/filesystem.ts @@ -0,0 +1,121 @@ +import type { InitChanges } from './types' +import type { InitOptions } from './args' + +import fs from 'node:fs' +import path from 'node:path' + +const SKIP_DIRECTORIES = new Set([ + '.git', + '.hg', + '.svn', + '.yarn', + 'node_modules', + 'dist', + 'build', + 'coverage', +]) + +const ensureDirectoryExists = (targetPath: string): void => { + if (!fs.existsSync(targetPath)) { + throw new Error(`Path not found: ${targetPath}`) + } + + const stat = fs.statSync(targetPath) + if (!stat.isDirectory()) { + throw new Error(`Target is not a directory: ${targetPath}`) + } +} + +export const resolvePackageJsonPath = (targetPath: string): string => { + if (path.basename(targetPath) === 'package.json') { + if (!fs.existsSync(targetPath)) { + throw new Error(`package.json not found: ${targetPath}`) + } + + return targetPath + } + + const packageJsonPath = path.resolve(targetPath, 'package.json') + + if (!fs.existsSync(packageJsonPath)) { + throw new Error(`package.json not found: ${packageJsonPath}`) + } + + return packageJsonPath +} + +export const collectPackageJsonPaths = (targetPath: string): string[] => { + const resolvedTarget = path.resolve(targetPath) + + if (!fs.existsSync(resolvedTarget)) { + throw new Error(`Path not found: ${resolvedTarget}`) + } + + if (path.basename(resolvedTarget) === 'package.json') { + return [resolvedTarget] + } + + ensureDirectoryExists(resolvedTarget) + + const packageJsonPaths: string[] = [] + + const visit = (directoryPath: string): void => { + const packageJsonPath = path.join(directoryPath, 'package.json') + if (fs.existsSync(packageJsonPath) && fs.statSync(packageJsonPath).isFile()) { + packageJsonPaths.push(packageJsonPath) + } + + for (const entry of fs.readdirSync(directoryPath, { withFileTypes: true })) { + if (!entry.isDirectory() || entry.isSymbolicLink()) { + continue + } + + if (SKIP_DIRECTORIES.has(entry.name)) { + continue + } + + visit(path.join(directoryPath, entry.name)) + } + } + + visit(resolvedTarget) + + return packageJsonPaths.sort() +} + +export const writeFileIfAllowed = ( + filePath: string, + content: string, + options: InitOptions, + changes: InitChanges +): boolean => { + if (fs.existsSync(filePath) && !options.forceFiles && !options.force) { + changes.warnings.push(`${filePath} already exists and will not be overwritten`) + return false + } + + if (!options.dryRun) { + fs.mkdirSync(path.dirname(filePath), { recursive: true }) + fs.writeFileSync(filePath, content, 'utf8') + } + + changes.files.push(filePath) + return true +} + +export const ensureDirectory = (directoryPath: string, options: InitOptions, changes: InitChanges): void => { + if (fs.existsSync(directoryPath)) { + if (!fs.statSync(directoryPath).isDirectory()) { + throw new Error(`Target path is not a directory: ${directoryPath}`) + } + + changes.skipped.push(`${directoryPath} already exists`) + return + } + + if (!options.dryRun) { + fs.mkdirSync(directoryPath, { recursive: true }) + } + + changes.directories.push(directoryPath) +} diff --git a/src/cmd/embed-ui/index.ts b/src/cmd/embed-ui/index.ts new file mode 100755 index 00000000..b8a1afe8 --- /dev/null +++ b/src/cmd/embed-ui/index.ts @@ -0,0 +1,492 @@ +import type { InitChanges } from './types' +import type { InitOptions } from './args' +import type { InstallablePackage, PackageChange } from './types' +import type { PackageManager, UpdateOptions } from './args' + +import { createInterface } from 'node:readline/promises' +import { execFileSync } from 'node:child_process' +import fs from 'node:fs' +import path from 'node:path' +import { pathToFileURL } from 'node:url' +import process from 'node:process' + +import { applyInitAgents } from './agents' +import { applyInitPackageConfigHooks } from './package-hooks' +import { applyInitPreflight } from './preflight' +import { collectPackageJsonPaths } from './filesystem' +import { + createEndpointWorker, + createEnvDts, + createEslintConfig, + createExtensionConfig, + createExtensionIcon, + createI18nIndex, +} from './templates' +import { createInitChanges } from './report' +import { createMessages, createOrderWidget, createPublishScript } from './templates' +import { createRange } from './packages' +import { createReadme } from './templates' +import { createSettingsPage, createTsConfig, createViteConfig } from './templates' +import { ensureDirectory } from './filesystem' +import { hasExistingDependency } from './package-json' +import { + I18N_RUNTIME_DEPENDENCY, + INIT_DEV_DEPENDENCIES, + INIT_RUNTIME_DEPENDENCIES, +} from './package-json' +import { installPackages } from './packages' +import { PACKAGE_MANAGERS, parseArgs, parseInitArgs } from './args' +import { printChanges, printInitReport } from './report' +import { promptForInstallSelection } from './packages' +import { readOrCreatePackageJson, readPackageJson } from './package-json' +import { resolveInstallPackages, resolveLatestVersion } from './packages' +import { resolvePackageJsonPath } from './filesystem' +import { ROOT_PACKAGE } from './packages' +import { setDependency, setMissingScript } from './package-json' +import { updatePackageJson } from './packages' +import { writeFileIfAllowed } from './filesystem' +import { writePackageJson } from './package-json' + +export type { CliOptions, InitOptions, UpdateOptions } from './args' +export { parseArgs, parseInitArgs } + +const DEFAULT_INIT_PACKAGE_IDS = ['embed-ui', 'components', 'contexts', 'types', 'endpoint'] +const DEFAULT_INIT_DIRS = ['endpoint', 'pages', 'widgets', 'shared', 'i18n'] + +const detectPackageManagerByLockfile = (cwd: string): PackageManager | null => { + const knownLockfiles = [ + { packageManager: 'yarn', file: 'yarn.lock' }, + { packageManager: 'npm', file: 'package-lock.json' }, + { packageManager: 'pnpm', file: 'pnpm-lock.yaml' }, + { packageManager: 'bun', file: 'bun.lockb' }, + ] satisfies Array<{ packageManager: PackageManager; file: string }> + const lockfiles = knownLockfiles.filter(({ file }) => fs.existsSync(path.join(cwd, file))) + + return lockfiles.length === 1 ? lockfiles[0].packageManager : null +} + +const resolvePackageManagerVersion = (packageManager: PackageManager): string | null => { + try { + return execFileSync(packageManager, ['--version'], { + encoding: 'utf8', + stdio: ['ignore', 'pipe', 'ignore'], + }).trim() + } catch { + return null + } +} + +const promptForPackageManager = async (): Promise => { + const readline = createInterface({ + input: process.stdin, + output: process.stdout, + }) + + try { + while (true) { + const answer = await readline.question('Choose package manager (yarn/npm/pnpm/bun): ') + if (PACKAGE_MANAGERS.includes(answer as PackageManager)) { + return answer as PackageManager + } + + console.error(`Unknown package manager: ${answer}`) + } + } finally { + readline.close() + } +} + +const resolvePackageManager = async ( + cwd: string, + explicitPackageManager: PackageManager | null +): Promise => { + if (explicitPackageManager) { + if (!PACKAGE_MANAGERS.includes(explicitPackageManager)) { + throw new Error(`Unknown package manager: ${explicitPackageManager}`) + } + + return explicitPackageManager + } + + const packageManager = detectPackageManagerByLockfile(cwd) + if (packageManager) { + return packageManager + } + + if (process.stdin.isTTY && process.stdout.isTTY) { + return promptForPackageManager() + } + + return 'npm' +} + +const resolveInitPackages = ( + tokens: string[] | null, + extraTokens: string[] | null +): InstallablePackage[] => { + const packageIds = tokens ?? [...DEFAULT_INIT_PACKAGE_IDS, ...(extraTokens ?? [])] + const packages = resolveInstallPackages(packageIds) + + for (const selectedPackage of packages) { + if (selectedPackage.id === 'testing') { + throw new Error('@retailcrm/embed-ui-v1-testing is not published for public init yet') + } + } + + return packages +} + +const resolveInitCwd = (options: InitOptions): string => { + const cwd = path.resolve(options.cwd) + + if (!fs.existsSync(cwd)) { + throw new Error(`cwd does not exist: ${cwd}`) + } + + if (!fs.statSync(cwd).isDirectory()) { + throw new Error(`cwd is not a directory: ${cwd}`) + } + + return cwd +} + +const resolveInitSourceRoot = (cwd: string, options: InitOptions): string => { + if (options.srcDir) { + return path.resolve(cwd, options.srcDir) + } + + if (options.target) { + return path.resolve(cwd, options.target) + } + + const srcPath = path.join(cwd, 'src') + if (!fs.existsSync(srcPath)) { + return srcPath + } + + return path.join(cwd, 'web') +} + +export const runUpdate = (options: UpdateOptions): void => { + const version = options.version ?? resolveLatestVersion() + const packageJsonPaths = collectPackageJsonPaths(options.target) + const reports: Array<{ packageJsonPath: string; updates: PackageChange[] }> = [] + + for (const packageJsonPath of packageJsonPaths) { + const { formatting, packageJson } = readPackageJson(packageJsonPath) + const updates = updatePackageJson(packageJson, version, options.exact) + + if (updates.length === 0) { + continue + } + + if (!options.dryRun) { + writePackageJson(packageJsonPath, packageJson, formatting) + } + + reports.push({ packageJsonPath, updates }) + } + + if (reports.length === 0) { + console.log(`No ${ROOT_PACKAGE}* dependencies found or changed under ${path.resolve(options.target)}`) + return + } + + const totalUpdates = reports.reduce((sum, report) => sum + report.updates.length, 0) + + console.log(`Resolved version: ${version}`) + for (const report of reports) { + console.log(report.packageJsonPath) + printChanges(report.updates) + } + + if (options.dryRun) { + console.log('Dry run enabled, package.json files were not modified') + return + } + + console.log( + `Updated ${totalUpdates} dependency entries in ${reports.length} package.json file(s) under ${path.resolve(options.target)}` + ) +} + +export const runAdd = async (options: UpdateOptions): Promise => { + const version = options.version ?? resolveLatestVersion() + const packageJsonPath = resolvePackageJsonPath(path.resolve(options.target)) + const { formatting, packageJson } = readPackageJson(packageJsonPath) + const selectedPackages = options.packages + ? resolveInstallPackages(options.packages) + : await promptForInstallSelection(packageJson) + + if (selectedPackages.length === 0) { + console.log('Nothing selected, package.json was not modified') + return + } + + const updates = installPackages(packageJson, selectedPackages, version, options.exact) + + if (updates.length === 0) { + console.log(`Selected packages are already installed with matching ranges in ${packageJsonPath}`) + return + } + + console.log(`Resolved version: ${version}`) + console.log(packageJsonPath) + printChanges(updates) + + if (options.dryRun) { + console.log('Dry run enabled, package.json was not modified') + return + } + + writePackageJson(packageJsonPath, packageJson, formatting) + console.log(`Installed ${updates.length} package entries in ${packageJsonPath}`) +} + +const applyInitPackageJson = ( + cwd: string, + selectedPackages: InstallablePackage[], + version: string, + packageManager: PackageManager, + options: InitOptions, + changes: InitChanges +): string => { + const packageJsonPath = path.join(cwd, 'package.json') + const { + created, + formatting, + packageJson, + } = readOrCreatePackageJson(packageJsonPath) + + if (!packageJson.type) { + packageJson.type = 'module' + changes.packageJson.push({ type: 'field', name: 'type', nextRange: 'module' }) + } else if (packageJson.type !== 'module') { + changes.warnings.push('package.json already has type field and it is not "module"') + } + + setMissingScript(packageJson, 'build', 'vite build', changes) + setMissingScript(packageJson, 'eslint', 'eslint .', changes) + setMissingScript(packageJson, 'eslint:fix', 'eslint --fix .', changes) + setMissingScript(packageJson, 'publish-extension', 'node scripts/publish-extension.mjs', changes) + + for (const selectedPackage of selectedPackages) { + setDependency( + packageJson, + selectedPackage.section, + selectedPackage.name, + createRange(version, options.exact), + changes, + options + ) + } + + for (const dependency of INIT_RUNTIME_DEPENDENCIES) { + if (dependency.name === I18N_RUNTIME_DEPENDENCY && hasExistingDependency(packageJson, dependency.name)) { + changes.skipped.push(`${dependency.name} already exists; i18n dependency setup skipped to avoid conflicts with existing project configuration`) + continue + } + + setDependency(packageJson, 'dependencies', dependency.name, dependency.range, changes, options) + } + + for (const dependency of INIT_DEV_DEPENDENCIES) { + setDependency(packageJson, 'devDependencies', dependency.name, dependency.range, changes, options) + } + + if (!packageJson.packageManager && options.packageManager) { + const packageManagerVersion = resolvePackageManagerVersion(packageManager) + + if (packageManagerVersion) { + const nextPackageManager = `${packageManager}@${packageManagerVersion}` + + packageJson.packageManager = nextPackageManager + changes.packageJson.push({ + type: 'field', + name: 'packageManager', + nextRange: nextPackageManager, + }) + } else { + changes.warnings.push(`Cannot resolve ${packageManager} version; packageManager field was not written`) + } + } + + if (!options.dryRun && (created || changes.packageJson.length > 0)) { + writePackageJson(packageJsonPath, packageJson, formatting) + } + + return packageJsonPath +} + +const applyInitDirectories = (sourceRoot: string, options: InitOptions, changes: InitChanges): void => { + if (options.noDirs || options.agentsOnly) { + return + } + + const dirs = options.dirs ?? DEFAULT_INIT_DIRS + const unknownDir = dirs.find((dir) => ![...DEFAULT_INIT_DIRS, 'src', 'tests'].includes(dir)) + if (unknownDir) { + throw new Error(`Unknown directory preset: ${unknownDir}`) + } + + ensureDirectory(sourceRoot, options, changes) + + for (const dir of dirs) { + if (dir === 'src') { + continue + } + + ensureDirectory(path.join(sourceRoot, dir), options, changes) + } + + if (dirs.includes('i18n')) { + ensureDirectory(path.join(sourceRoot, 'i18n/locales'), options, changes) + } +} + +const applyInitConfigs = ( + cwd: string, + sourceRoot: string, + options: InitOptions, + changes: InitChanges +): void => { + if (options.agentsOnly) { + return + } + + writeFileIfAllowed(path.join(cwd, 'tsconfig.json'), createTsConfig(cwd, sourceRoot), options, changes) + writeFileIfAllowed(path.join(cwd, 'vite.config.ts'), createViteConfig(cwd, sourceRoot), options, changes) + writeFileIfAllowed(path.join(cwd, 'env.d.ts'), createEnvDts(), options, changes) + writeFileIfAllowed(path.join(cwd, 'eslint.config.js'), createEslintConfig(cwd, sourceRoot), options, changes) +} + +const applyInitTemplate = ( + cwd: string, + sourceRoot: string, + packageManager: PackageManager, + options: InitOptions, + changes: InitChanges +): void => { + if (options.noTemplate || options.agentsOnly) { + return + } + + if (options.template !== 'order-card') { + throw new Error(`Unknown template: ${options.template}`) + } + + writeFileIfAllowed( + path.join(sourceRoot, 'endpoint/endpoint.worker.ts'), + createEndpointWorker(options), + options, + changes + ) + writeFileIfAllowed(path.join(sourceRoot, 'shared/assets/extension.svg'), createExtensionIcon(), options, changes) + writeFileIfAllowed(path.join(sourceRoot, 'i18n/index.ts'), createI18nIndex(), options, changes) + writeFileIfAllowed(path.join(sourceRoot, 'i18n/locales/en-GB.json'), createMessages(), options, changes) + writeFileIfAllowed(path.join(sourceRoot, 'i18n/locales/es-ES.json'), createMessages(), options, changes) + writeFileIfAllowed(path.join(sourceRoot, 'i18n/locales/ru-RU.json'), createMessages(), options, changes) + writeFileIfAllowed(path.join(sourceRoot, 'pages/SettingsPage.vue'), createSettingsPage(), options, changes) + writeFileIfAllowed(path.join(sourceRoot, 'widgets/OrderCommonAfterWidget.vue'), createOrderWidget(), options, changes) + writeFileIfAllowed(path.join(cwd, 'extensionrc.json'), createExtensionConfig(options), options, changes) + writeFileIfAllowed(path.join(cwd, 'scripts/publish-extension.mjs'), createPublishScript(), options, changes) + writeFileIfAllowed(path.join(cwd, 'README.md'), createReadme(cwd, sourceRoot, options, packageManager), options, changes) +} + +const runInstall = ( + cwd: string, + packageManager: PackageManager, + options: InitOptions, + changes: InitChanges, + packageJsonChanged: boolean +): void => { + if (options.noInstall || options.agentsOnly) { + return + } + + if (!packageJsonChanged && !options.force) { + changes.skipped.push('install skipped because package.json was not changed') + return + } + + const args = ['install'] + changes.install = `${packageManager} ${args.join(' ')}` + + if (options.dryRun) { + return + } + + execFileSync(packageManager, args, { + cwd, + stdio: 'inherit', + }) +} + +export const runInit = async (options: InitOptions): Promise => { + const cwd = resolveInitCwd(options) + const sourceRoot = resolveInitSourceRoot(cwd, options) + + if (fs.existsSync(sourceRoot) && !fs.statSync(sourceRoot).isDirectory()) { + throw new Error(`Target path is not a directory: ${sourceRoot}`) + } + + const selectedPackages = resolveInitPackages(options.packages, options.with) + const version = options.agentsOnly + ? options.version ?? 'not used' + : options.version ?? resolveLatestVersion() + const packageManager = options.agentsOnly + ? options.packageManager ?? detectPackageManagerByLockfile(cwd) ?? 'npm' + : await resolvePackageManager(cwd, options.packageManager) + const changes = createInitChanges() + + applyInitPreflight(cwd, sourceRoot, packageManager, selectedPackages, version, options, changes) + + let packageJsonPath: string | null = null + if (!options.agentsOnly) { + packageJsonPath = applyInitPackageJson(cwd, selectedPackages, version, packageManager, options, changes) + applyInitDirectories(sourceRoot, options, changes) + applyInitConfigs(cwd, sourceRoot, options, changes) + applyInitTemplate(cwd, sourceRoot, packageManager, options, changes) + applyInitPackageConfigHooks(cwd, selectedPackages, packageManager, options, changes) + } + + applyInitAgents(cwd, selectedPackages, packageManager, options, changes) + runInstall(cwd, packageManager, options, changes, Boolean(packageJsonPath && changes.packageJson.length > 0)) + printInitReport(cwd, sourceRoot, version, packageManager, changes, options) +} + +export const main = async (argv: string[] = process.argv.slice(2)): Promise => { + const options = parseArgs(argv) + + if (options.command === 'init') { + await runInit(options) + return + } + + if (options.add) { + await runAdd(options) + return + } + + runUpdate(options) +} + +const isExecutedDirectly = (): boolean => { + const entryPath = process.argv[1] + + if (!entryPath) { + return false + } + + return pathToFileURL(path.resolve(entryPath)).href === import.meta.url +} + +if (isExecutedDirectly()) { + try { + await main() + } catch (error) { + const message = error instanceof Error ? error.message : String(error) + console.error(message) + process.exit(1) + } +} diff --git a/src/cmd/embed-ui/package-hook-runner.ts b/src/cmd/embed-ui/package-hook-runner.ts new file mode 100644 index 00000000..f8ae83f3 --- /dev/null +++ b/src/cmd/embed-ui/package-hook-runner.ts @@ -0,0 +1,142 @@ +import type { InitChanges } from './types' +import type { InitOptions } from './args' +import type { InstallablePackageHook } from './types' +import type { PackageManager } from './args' + +import { execFileSync } from 'node:child_process' +import fs from 'node:fs' +import path from 'node:path' + +interface ResolvedHookCommand { + command: string; + args: string[]; + display: string; + source: 'local' | 'transient'; +} + +const resolveLocalBinPath = (cwd: string, binName: string): string | null => { + const binPath = path.join(cwd, 'node_modules', '.bin', process.platform === 'win32' ? `${binName}.cmd` : binName) + + return fs.existsSync(binPath) ? binPath : null +} + +const hasLocalPackage = (cwd: string, packageName: string): boolean => + fs.existsSync(path.join(cwd, 'node_modules', packageName, 'package.json')) + +const resolveDownloadCommand = ( + packageName: string, + binName: string, + packageManager: PackageManager, + args: string[] +): ResolvedHookCommand => { + if (packageManager === 'yarn') { + const commandArgs = ['dlx', '-p', packageName, binName, ...args] + + return { + command: 'yarn', + args: commandArgs, + display: `yarn ${commandArgs.join(' ')}`, + source: 'transient', + } + } + + if (packageManager === 'pnpm') { + const commandArgs = ['dlx', '--package', packageName, binName, ...args] + + return { + command: 'pnpm', + args: commandArgs, + display: `pnpm ${commandArgs.join(' ')}`, + source: 'transient', + } + } + + if (packageManager === 'bun') { + const commandArgs = ['x', '--package', packageName, binName, ...args] + + return { + command: 'bun', + args: commandArgs, + display: `bun ${commandArgs.join(' ')}`, + source: 'transient', + } + } + + const commandArgs = ['exec', '--yes', '--package', packageName, '--', binName, ...args] + + return { + command: 'npm', + args: commandArgs, + display: `npm ${commandArgs.join(' ')}`, + source: 'transient', + } +} + +export const resolvePackageHookCommand = ( + cwd: string, + packageName: string, + binName: string, + packageManager: PackageManager, + args: string[] +): ResolvedHookCommand => { + const localBinPath = resolveLocalBinPath(cwd, binName) + + if (localBinPath) { + return { + command: localBinPath, + args, + display: `${localBinPath} ${args.join(' ')}`, + source: 'local', + } + } + + if (hasLocalPackage(cwd, packageName)) { + throw new Error( + `${packageName} is installed, but ${binName} was not found in node_modules/.bin. ` + + 'Reinstall dependencies or check the package bin metadata.' + ) + } + + return resolveDownloadCommand(packageName, binName, packageManager, args) +} + +const getExecErrorMessage = (error: unknown): string => { + if (error instanceof Error && error.message) { + return error.message + } + + return String(error) +} + +export const runPackageHookCommand = ( + cwd: string, + packageName: string, + binName: string, + packageManager: PackageManager, + args: string[], + failureMode: InstallablePackageHook['failureMode'], + options: InitOptions, + changes: InitChanges +): void => { + const command = resolvePackageHookCommand(cwd, packageName, binName, packageManager, args) + + changes.hooks.push(command.display) + + if (options.dryRun) { + return + } + + try { + execFileSync(command.command, command.args, { + cwd, + stdio: 'inherit', + }) + } catch (error) { + if (command.source === 'transient' && failureMode === 'advisory') { + changes.warnings.push(`Package hook ${command.display} was skipped: ${getExecErrorMessage(error)}`) + return + } + + throw error + } +} diff --git a/src/cmd/embed-ui/package-hooks.ts b/src/cmd/embed-ui/package-hooks.ts new file mode 100644 index 00000000..bd2912c6 --- /dev/null +++ b/src/cmd/embed-ui/package-hooks.ts @@ -0,0 +1,47 @@ +import type { InitChanges } from './types' +import type { InitOptions } from './args' +import type { InstallablePackage } from './types' +import type { PackageManager } from './args' + +import { runPackageHookCommand } from './package-hook-runner' + +export const applyInitPackageConfigHooks = ( + cwd: string, + selectedPackages: InstallablePackage[], + packageManager: PackageManager, + options: InitOptions, + changes: InitChanges +): void => { + for (const selectedPackage of selectedPackages) { + for (const hook of selectedPackage.hooks ?? []) { + if (hook.type !== 'config') { + continue + } + + if (hook.requiresMcp && options.noMcp) { + continue + } + + const args = [hook.command, cwd] + + if (hook.requiresMcp && (options.force || options.forceMcp)) { + args.push('--force') + } + + if (hook.requiresMcp && options.mcpClientConfigs?.length) { + args.push('--mcp-client-configs', options.mcpClientConfigs.join(',')) + } + + runPackageHookCommand( + cwd, + selectedPackage.name, + hook.binName, + packageManager, + args, + hook.failureMode, + options, + changes + ) + } + } +} diff --git a/src/cmd/embed-ui/package-json.ts b/src/cmd/embed-ui/package-json.ts new file mode 100644 index 00000000..d3a8a8bb --- /dev/null +++ b/src/cmd/embed-ui/package-json.ts @@ -0,0 +1,224 @@ +import type { + DependencySection, + Formatting, + InitChanges, + PackageJson, +} from './types' + +import fs from 'node:fs' + +import { findDependencySection, formatRange, isTargetPackage } from './packages' + +export const DEFAULT_INDENT = ' ' +export const DEFAULT_NEWLINE = '\n' + +export const INIT_RUNTIME_DEPENDENCIES: Array<{ name: string; range: string }> = [ + { name: '@omnicajs/vue-remote', range: '^0.2.23' }, + { name: 'pinia', range: '^2.2' }, + { name: 'vue', range: '^3.5' }, + { name: 'vue-i18n', range: '^11' }, +] + +export const INIT_DEV_DEPENDENCIES: Array<{ name: string; range: string }> = [ + { name: '@eslint/js', range: '^9.39' }, + { name: '@intlify/eslint-plugin-vue-i18n', range: '~4.3.0' }, + { name: '@intlify/unplugin-vue-i18n', range: '^11.1' }, + { name: '@omnicajs/eslint-plugin-dependencies', range: '^0.0.2' }, + { name: '@types/node', range: '^22.19' }, + { name: '@vitejs/plugin-vue', range: '^6.0' }, + { name: '@vue/language-server', range: '^3.2' }, + { name: 'eslint', range: '^9.39' }, + { name: 'eslint-plugin-vue', range: '^10.9' }, + { name: 'globals', range: '^16.5' }, + { name: 'less', range: '^4.6' }, + { name: 'typescript', range: '^5.9' }, + { name: 'typescript-eslint', range: '^8.59' }, + { name: 'vite', range: '^7.3' }, + { name: 'vite-svg-loader', range: '^5.1' }, + { name: 'vue-eslint-parser', range: '^10.4' }, +] + +export const I18N_RUNTIME_DEPENDENCY = 'vue-i18n' + +export const hasExistingDependency = (packageJson: PackageJson, name: string): boolean => + findDependencySection(packageJson, name) !== null + +export const detectFormatting = (source: string): Formatting => { + const newline = source.includes('\r\n') ? '\r\n' : DEFAULT_NEWLINE + const indentMatch = source.match(/\n([ \t]+)"/) + + return { + indent: indentMatch?.[1] ?? DEFAULT_INDENT, + newline, + trailingNewline: source.endsWith('\n') || source.endsWith('\r\n'), + } +} + +export const serializePackageJson = (packageJson: PackageJson, formatting: Formatting): string => { + const serialized = JSON.stringify(packageJson, null, formatting.indent) + .replace(/\n/g, formatting.newline) + + return formatting.trailingNewline + ? `${serialized}${formatting.newline}` + : serialized +} + +export const readPackageJson = (packageJsonPath: string): { formatting: Formatting; packageJson: PackageJson } => { + const source = fs.readFileSync(packageJsonPath, 'utf8') + + return { + formatting: detectFormatting(source), + packageJson: JSON.parse(source), + } +} + +export const writePackageJson = (packageJsonPath: string, packageJson: PackageJson, formatting: Formatting): void => { + fs.writeFileSync(packageJsonPath, serializePackageJson(packageJson, formatting), 'utf8') +} + +export const readOrCreatePackageJson = ( + packageJsonPath: string +): { created: boolean; formatting: Formatting; packageJson: PackageJson } => { + if (fs.existsSync(packageJsonPath)) { + return { + created: false, + ...readPackageJson(packageJsonPath), + } + } + + return { + created: true, + formatting: { + indent: DEFAULT_INDENT, + newline: DEFAULT_NEWLINE, + trailingNewline: true, + }, + packageJson: { + name: 'retailcrm-extension-frontend', + private: true, + type: 'module', + scripts: { + build: 'vite build', + eslint: 'eslint .', + 'eslint:fix': 'eslint --fix .', + }, + dependencies: {}, + devDependencies: {}, + }, + } +} + +const ensureObjectField = (object: PackageJson, field: string): PackageJson => { + if (!object[field] || typeof object[field] !== 'object' || Array.isArray(object[field])) { + object[field] = {} + } + + return object[field] as PackageJson +} + +const resolveRangeMajor = (range: string): number | null => { + const match = range.match(/\d+/u) + + return match ? Number(match[0]) : null +} + +const isCompatibleRange = (currentRange: string, expectedRange: string): boolean => { + const currentMajor = resolveRangeMajor(currentRange) + const expectedMajor = resolveRangeMajor(expectedRange) + + return currentMajor !== null && expectedMajor !== null && currentMajor === expectedMajor +} + +export const setMissingScript = ( + packageJson: PackageJson, + name: string, + command: string, + changes: InitChanges +): void => { + const scripts = ensureObjectField(packageJson, 'scripts') + + if (scripts[name] === command) { + return + } + + if (typeof scripts[name] === 'string') { + changes.warnings.push(`script "${name}" already exists and will not be overwritten`) + return + } + + scripts[name] = command + + changes.packageJson.push({ + type: 'script', + name, + nextRange: command, + }) +} + +export const setDependency = ( + packageJson: PackageJson, + section: DependencySection, + name: string, + range: string, + changes: InitChanges, + options: { + fixSections?: boolean; + forceDeps?: boolean; + } = {} +): void => { + let currentSection = findDependencySection(packageJson, name) + + if (currentSection && currentSection !== section) { + if (options.fixSections) { + const previousSection = currentSection + const currentDependencyMap = packageJson[currentSection] as Record + const nextDependencyMap = ensureObjectField(packageJson, section) + + nextDependencyMap[name] = currentDependencyMap[name] + delete currentDependencyMap[name] + currentSection = section + + changes.packageJson.push({ + type: 'update', + section, + name, + currentRange: `in ${previousSection}`, + nextRange: `move to ${section}`, + }) + } else { + changes.warnings.push(`${name} already exists in ${currentSection}; expected ${section}. Use --fix-sections to move it.`) + return + } + } + + const dependencyMap = ensureObjectField(packageJson, section) + const currentRange = dependencyMap[name] + + if (currentRange === range) { + return + } + + if (typeof currentRange === 'string' && !isTargetPackage(name)) { + if (isCompatibleRange(currentRange, range) && !options.forceDeps) { + return + } + + if (!options.forceDeps) { + changes.warnings.push(`${name} has range ${currentRange}; expected compatible ${range}. Use --force-deps to replace it.`) + return + } + } + + dependencyMap[name] = typeof currentRange === 'string' + ? formatRange(currentRange, range.replace(/^[~^]/u, ''), range === range.replace(/^[~^]/u, '')) + : range + const nextRange = String(dependencyMap[name]) + + changes.packageJson.push({ + type: typeof currentRange === 'string' ? 'update' : 'install', + section, + name, + currentRange: typeof currentRange === 'string' ? currentRange : null, + nextRange, + }) +} diff --git a/src/cmd/embed-ui/packages.ts b/src/cmd/embed-ui/packages.ts new file mode 100644 index 00000000..61cd69d2 --- /dev/null +++ b/src/cmd/embed-ui/packages.ts @@ -0,0 +1,285 @@ +import type { + DependencySection, + InstallablePackage, + PackageChange, + PackageJson, +} from './types' + +import { createInterface } from 'node:readline/promises' +import { execFileSync } from 'node:child_process' +import process from 'node:process' + +import { parsePackageList } from './args' +import { TARGET_SECTIONS } from './types' + +export const ROOT_PACKAGE = '@retailcrm/embed-ui' + +export const INSTALLABLE_PACKAGES: InstallablePackage[] = [ + { + id: 'embed-ui', + name: ROOT_PACKAGE, + section: 'dependencies', + description: 'Базовый пакет с общим API и согласованными v1-зависимостями.', + }, + { + id: 'components', + name: '@retailcrm/embed-ui-v1-components', + section: 'dependencies', + description: 'UI-компоненты для host/remote приложений.', + hooks: [ + { + type: 'agents', + binName: 'embed-ui-v1-components', + command: 'init-agents', + failureMode: 'advisory', + }, + ], + }, + { + id: 'contexts', + name: '@retailcrm/embed-ui-v1-contexts', + section: 'dependencies', + description: 'Реактивные контексты RetailCRM JS API.', + }, + { + id: 'types', + name: '@retailcrm/embed-ui-v1-types', + section: 'dependencies', + description: 'Базовые type declarations для RetailCRM JS API.', + }, + { + id: 'testing', + name: '@retailcrm/embed-ui-v1-testing', + section: 'devDependencies', + description: 'Вспомогательные утилиты и типы для тестов интеграций.', + }, + { + id: 'endpoint', + name: '@retailcrm/embed-ui-v1-endpoint', + section: 'dependencies', + description: 'Endpoint API для интеграций в RetailCRM.', + hooks: [ + { + type: 'agents', + binName: 'embed-ui-v1-endpoint', + command: 'init-agents', + failureMode: 'advisory', + requiresMcp: true, + }, + { + type: 'config', + binName: 'embed-ui-v1-endpoint', + command: 'init-config', + failureMode: 'advisory', + requiresMcp: true, + }, + ], + }, +] + +export const resolveLatestVersion = (): string => { + const output = execFileSync( + 'npm', + ['view', ROOT_PACKAGE, 'version'], + { + encoding: 'utf8', + stdio: ['ignore', 'pipe', 'pipe'], + } + ).trim() + + if (!output) { + throw new Error(`Cannot resolve latest version for ${ROOT_PACKAGE}`) + } + + return output +} + +export const isTargetPackage = (name: string): boolean => + name === ROOT_PACKAGE || name.startsWith(`${ROOT_PACKAGE}-`) + +export const createRange = (version: string, exact: boolean): string => exact ? version : `^${version}` + +export const formatRange = (currentRange: string, nextVersion: string, exact: boolean): string => { + if (exact) { + return nextVersion + } + + if (currentRange.startsWith('workspace:')) { + return currentRange + } + + if (currentRange.startsWith('~')) { + return `~${nextVersion}` + } + + if (currentRange.startsWith('^')) { + return `^${nextVersion}` + } + + return `^${nextVersion}` +} + +export const findDependencySection = (packageJson: PackageJson, packageName: string): DependencySection | null => { + for (const section of TARGET_SECTIONS) { + const dependencyMap = packageJson[section] as Record | undefined + + if (dependencyMap && typeof dependencyMap === 'object' && packageName in dependencyMap) { + return section + } + } + + return null +} + +export const updatePackageJson = ( + packageJson: PackageJson, + version: string, + exact: boolean +): PackageChange[] => { + const updates: PackageChange[] = [] + + for (const section of TARGET_SECTIONS) { + const dependencyMap = packageJson[section] as Record | undefined + + if (!dependencyMap || typeof dependencyMap !== 'object') { + continue + } + + for (const [name, currentRange] of Object.entries(dependencyMap)) { + if (!isTargetPackage(name) || typeof currentRange !== 'string') { + continue + } + + const nextRange = formatRange(currentRange, version, exact) + if (nextRange === currentRange) { + continue + } + + dependencyMap[name] = nextRange + updates.push({ + type: 'update', + section, + name, + currentRange, + nextRange, + }) + } + } + + return updates +} + +export const resolveInstallPackages = (tokens: string[]): InstallablePackage[] => { + const selectedPackages: InstallablePackage[] = [] + const seen = new Set() + + for (const token of tokens) { + const normalized = token.trim() + if (!normalized) { + continue + } + + const numericIndex = Number(normalized) + const selectedPackage = + Number.isInteger(numericIndex) && numericIndex >= 1 && numericIndex <= INSTALLABLE_PACKAGES.length + ? INSTALLABLE_PACKAGES[numericIndex - 1] + : INSTALLABLE_PACKAGES.find((entry) => entry.id === normalized || entry.name === normalized) + + if (!selectedPackage) { + const supported = INSTALLABLE_PACKAGES + .map((entry, index) => `${index + 1}/${entry.id}/${entry.name}`) + .join(', ') + + throw new Error(`Unknown add target "${normalized}". Supported values: ${supported}`) + } + + if (seen.has(selectedPackage.name)) { + continue + } + + seen.add(selectedPackage.name) + selectedPackages.push(selectedPackage) + } + + return selectedPackages +} + +export const installPackages = ( + packageJson: PackageJson, + packages: InstallablePackage[], + version: string, + exact: boolean +): PackageChange[] => { + const updates: PackageChange[] = [] + + for (const selectedPackage of packages) { + const section = findDependencySection(packageJson, selectedPackage.name) ?? selectedPackage.section + const dependencyMap = (packageJson[section] ?? {}) as Record + + if (!(section in packageJson)) { + packageJson[section] = dependencyMap + } + + const currentRange = dependencyMap[selectedPackage.name] + const nextRange = typeof currentRange === 'string' + ? formatRange(currentRange, version, exact) + : createRange(version, exact) + + if (currentRange === nextRange) { + continue + } + + dependencyMap[selectedPackage.name] = nextRange + updates.push({ + type: typeof currentRange === 'string' ? 'update' : 'install', + section, + name: selectedPackage.name, + currentRange: typeof currentRange === 'string' ? currentRange : null, + nextRange, + }) + } + + return updates +} + +export const promptForInstallSelection = async (packageJson: PackageJson): Promise => { + if (!process.stdin.isTTY || !process.stdout.isTTY) { + throw new Error('Interactive add mode requires a TTY. Use --packages to select packages explicitly.') + } + + console.log('Выберите пакеты для установки в текущий package.json:') + for (const [index, selectedPackage] of INSTALLABLE_PACKAGES.entries()) { + const currentSection = findDependencySection(packageJson, selectedPackage.name) + const installedHint = currentSection ? ` Уже есть в ${currentSection}.` : '' + + console.log(` ${index + 1}. ${selectedPackage.name} (${selectedPackage.id})`) + console.log(` ${selectedPackage.description} Раздел по умолчанию: ${selectedPackage.section}.${installedHint}`) + } + + const readline = createInterface({ + input: process.stdin, + output: process.stdout, + }) + + try { + while (true) { + const answer = await readline.question( + 'Введите номера, ids или имена пакетов через запятую (например: 1,3 или components,types): ' + ) + + const tokens = parsePackageList(answer) + if (tokens.length === 0) { + return [] + } + + try { + return resolveInstallPackages(tokens) + } catch (error) { + const message = error instanceof Error ? error.message : String(error) + console.error(message) + } + } + } finally { + readline.close() + } +} diff --git a/src/cmd/embed-ui/preflight.ts b/src/cmd/embed-ui/preflight.ts new file mode 100644 index 00000000..2bdd1da5 --- /dev/null +++ b/src/cmd/embed-ui/preflight.ts @@ -0,0 +1,402 @@ +import type { InitChanges } from './types' +import type { InitOptions } from './args' +import type { InstallablePackage, PackageJson } from './types' +import type { PackageManager } from './args' + +import fs from 'node:fs' +import path from 'node:path' + +import { findDependencySection } from './packages' +import { + hasExistingDependency, + I18N_RUNTIME_DEPENDENCY, + INIT_DEV_DEPENDENCIES, + INIT_RUNTIME_DEPENDENCIES, + readPackageJson, +} from './package-json' + +const LOCKFILES: Array<{ file: string; packageManager: PackageManager }> = [ + { file: 'yarn.lock', packageManager: 'yarn' }, + { file: 'package-lock.json', packageManager: 'npm' }, + { file: 'pnpm-lock.yaml', packageManager: 'pnpm' }, + { file: 'bun.lockb', packageManager: 'bun' }, +] + +const CONFIG_FILES = [ + 'tsconfig.json', + 'vite.config.ts', + 'vite.config.js', + 'vite.config.mts', + 'eslint.config.js', + 'eslint.config.mjs', + 'env.d.ts', +] as const + +const SCRIPT_NAMES = ['build', 'dev', 'eslint', 'eslint:fix', 'lint', 'test'] as const + +const VITE_CONFIG_FILES = [ + 'vite.config.ts', + 'vite.config.js', + 'vite.config.mts', +] as const + +const ESLINT_CONFIG_FILES = [ + 'eslint.config.js', + 'eslint.config.mjs', +] as const + +const TEMPLATE_FILE_IMPACTS = [ + { + relativePath: 'endpoint/endpoint.worker.ts', + impact: 'endpoint runner entry will not be generated', + }, + { + relativePath: 'pages/SettingsPage.vue', + impact: 'starter settings page will not be generated', + }, + { + relativePath: 'widgets/OrderCommonAfterWidget.vue', + impact: 'starter order widget will not be generated', + }, + { + relativePath: 'i18n/index.ts', + impact: 'starter i18n bootstrap will not be generated', + }, + { + relativePath: 'i18n/locales/en-GB.json', + impact: 'starter English locale messages will not be generated', + }, +] as const + +const hasEnabledMcpConfigHook = (selectedPackages: InstallablePackage[], options: InitOptions): boolean => + !options.noMcp && selectedPackages.some((selectedPackage) => + selectedPackage.hooks?.some((hook) => hook.type === 'config' && hook.requiresMcp) ?? false + ) + +const readTextIfExists = (filePath: string): string | null => { + if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) { + return null + } + + return fs.readFileSync(filePath, 'utf8') +} + +const hasTextMarker = (content: string, markers: string[]): boolean => + markers.some((marker) => content.includes(marker)) + +const normalizeRelativePath = (relativePath: string): string => + relativePath.split(path.sep).join('/') + +const getSourceRootRelative = (cwd: string, sourceRoot: string): string => + normalizeRelativePath(path.relative(cwd, sourceRoot) || '.') + +const resolveRangeMajor = (range: string): number | null => { + const match = range.match(/\d+/u) + + return match ? Number(match[0]) : null +} + +const describePathState = (cwd: string, relativePath: string): string => { + const targetPath = path.join(cwd, relativePath) + + if (!fs.existsSync(targetPath)) { + return `${relativePath}: missing` + } + + return `${relativePath}: found` +} + +const readExistingPackageJson = ( + packageJsonPath: string, + changes: InitChanges +): PackageJson | null => { + if (!fs.existsSync(packageJsonPath)) { + changes.preflight.push('package.json: missing; it will be created') + return null + } + + const { packageJson } = readPackageJson(packageJsonPath) + changes.preflight.push('package.json: found') + + return packageJson +} + +const analyzeDependency = ( + packageJson: PackageJson, + name: string, + expectedRange: string, + expectedSection: string, + options: InitOptions, + changes: InitChanges +): void => { + const section = findDependencySection(packageJson, name) + + if (!section) { + return + } + + const dependencyMap = packageJson[section] + const currentRange = typeof dependencyMap === 'object' && dependencyMap + ? (dependencyMap as Record)[name] + : null + + if (section !== expectedSection) { + if (options.fixSections) { + changes.preflight.push(`${name}: will move from ${section} to ${expectedSection}`) + } else { + changes.warnings.push(`${name} already exists in ${section}; expected ${expectedSection}. Use --fix-sections to move it.`) + } + } + + if (typeof currentRange !== 'string') { + return + } + + const currentMajor = resolveRangeMajor(currentRange) + const expectedMajor = resolveRangeMajor(expectedRange) + + if (currentMajor !== null && expectedMajor !== null && currentMajor !== expectedMajor) { + if (options.forceDeps) { + changes.preflight.push(`${name}: will replace ${currentRange} with ${expectedRange}`) + } else { + changes.warnings.push(`${name} has range ${currentRange}; expected compatible ${expectedRange}. Use --force-deps to replace it.`) + } + } +} + +const analyzePackageJson = ( + packageJson: PackageJson, + selectedPackages: InstallablePackage[], + version: string, + options: InitOptions, + changes: InitChanges +): void => { + if (packageJson.type === 'module') { + changes.preflight.push('package.json type: module') + } else if (packageJson.type) { + changes.warnings.push(`package.json already has type "${String(packageJson.type)}"; expected "module"`) + } else { + changes.preflight.push('package.json type: missing; "module" will be added') + } + + const scripts = packageJson.scripts + if (scripts && typeof scripts === 'object' && !Array.isArray(scripts)) { + for (const scriptName of SCRIPT_NAMES) { + if (scriptName in scripts) { + changes.preflight.push(`script ${scriptName}: found`) + } + } + } + + const selectedRange = options.exact ? version : `^${version}` + for (const selectedPackage of selectedPackages) { + analyzeDependency(packageJson, selectedPackage.name, selectedRange, selectedPackage.section, options, changes) + } + + for (const dependency of INIT_RUNTIME_DEPENDENCIES) { + if (dependency.name === I18N_RUNTIME_DEPENDENCY && hasExistingDependency(packageJson, dependency.name)) { + changes.preflight.push(`${dependency.name}: found; i18n dependency setup will be skipped to avoid conflicts with existing project configuration`) + continue + } + + analyzeDependency(packageJson, dependency.name, dependency.range, 'dependencies', options, changes) + } + + for (const dependency of INIT_DEV_DEPENDENCIES) { + analyzeDependency(packageJson, dependency.name, dependency.range, 'devDependencies', options, changes) + } +} + +const analyzeTsConfig = ( + cwd: string, + sourceRoot: string, + changes: InitChanges +): void => { + const tsconfigPath = path.join(cwd, 'tsconfig.json') + const content = readTextIfExists(tsconfigPath) + + if (!content) { + return + } + + let parsed: PackageJson + try { + parsed = JSON.parse(content) as PackageJson + } catch { + changes.warnings.push('tsconfig.json: cannot parse JSON; verify @ alias, JSON imports, and vue-remote tooling manually') + return + } + + const compilerOptions = parsed.compilerOptions && typeof parsed.compilerOptions === 'object' + ? parsed.compilerOptions as PackageJson + : {} + const vueCompilerOptions = parsed.vueCompilerOptions && typeof parsed.vueCompilerOptions === 'object' + ? parsed.vueCompilerOptions as PackageJson + : {} + const sourceRootRelative = getSourceRootRelative(cwd, sourceRoot) + + if (compilerOptions.moduleResolution !== 'Bundler') { + changes.warnings.push('tsconfig.json: moduleResolution is not "Bundler"; Vite-style imports may resolve differently') + } + + if (compilerOptions.resolveJsonModule !== true) { + changes.warnings.push('tsconfig.json: resolveJsonModule is not enabled; JSON locale imports may not type-check') + } + + const paths = compilerOptions.paths && typeof compilerOptions.paths === 'object' + ? compilerOptions.paths as Record + : null + const aliasTarget = paths?.['@/*'] + + if (!Array.isArray(aliasTarget)) { + changes.warnings.push('tsconfig.json: @/* path alias is missing; generated imports use @/') + } else if (!aliasTarget.includes(`${sourceRootRelative}/*`)) { + changes.warnings.push(`tsconfig.json: @/* path alias does not point to ${sourceRootRelative}/*`) + } + + const plugins = Array.isArray(vueCompilerOptions.plugins) + ? vueCompilerOptions.plugins + : [] + + if (!plugins.includes('@omnicajs/vue-remote/tooling')) { + changes.warnings.push('tsconfig.json: @omnicajs/vue-remote/tooling plugin is missing; remote script modifiers may not be typed') + } +} + +const analyzeViteConfig = ( + cwd: string, + sourceRoot: string, + changes: InitChanges +): void => { + const viteConfig = VITE_CONFIG_FILES + .map((file) => ({ file, content: readTextIfExists(path.join(cwd, file)) })) + .find(({ content }) => content !== null) + + if (!viteConfig?.content) { + return + } + + const sourceRootRelative = getSourceRootRelative(cwd, sourceRoot) + + if (!hasTextMarker(viteConfig.content, ['@omnicajs/vue-remote/vite-plugin', 'vueRemoteVitePlugin'])) { + changes.warnings.push(`${viteConfig.file}: @omnicajs/vue-remote/vite-plugin is missing; remote event modifiers will not be transformed`) + } + + if (!hasTextMarker(viteConfig.content, ['@intlify/unplugin-vue-i18n/vite', 'vueI18n'])) { + changes.warnings.push(`${viteConfig.file}: vue-i18n Vite plugin is missing; JSON and SFC locale blocks may not be bundled`) + } + + if (!hasTextMarker(viteConfig.content, ['vite-svg-loader', 'defaultImport: \'component\'', 'defaultImport: "component"'])) { + changes.warnings.push(`${viteConfig.file}: SVG component loader is missing; generated SVG component imports may fail`) + } + + if (!hasTextMarker(viteConfig.content, ['\'@\'', '"@"'])) { + changes.warnings.push(`${viteConfig.file}: @ alias is missing; generated imports use @/`) + } else if (!viteConfig.content.includes(sourceRootRelative) && !viteConfig.content.includes(path.basename(sourceRoot))) { + changes.warnings.push(`${viteConfig.file}: @ alias may not point to ${sourceRootRelative}`) + } +} + +const analyzeEslintConfig = (cwd: string, changes: InitChanges): void => { + const eslintConfig = ESLINT_CONFIG_FILES + .map((file) => ({ file, content: readTextIfExists(path.join(cwd, file)) })) + .find(({ content }) => content !== null) + + if (!eslintConfig?.content) { + return + } + + if (!eslintConfig.content.includes('@intlify/eslint-plugin-vue-i18n')) { + changes.warnings.push(`${eslintConfig.file}: @intlify/eslint-plugin-vue-i18n is missing; dynamic or missing translation keys will not be guarded`) + } + + if (!eslintConfig.content.includes('@omnicajs/eslint-plugin-dependencies')) { + changes.warnings.push(`${eslintConfig.file}: @omnicajs/eslint-plugin-dependencies is missing; generated import ordering may not be enforced`) + } + + if (!eslintConfig.content.includes('vue/block-order')) { + changes.warnings.push(`${eslintConfig.file}: vue/block-order is missing; generated Vue block order may drift from the template`) + } +} + +const analyzeTemplateFileSkips = ( + cwd: string, + sourceRoot: string, + options: InitOptions, + changes: InitChanges +): void => { + if (options.noTemplate || options.force || options.forceFiles) { + return + } + + for (const { relativePath, impact } of TEMPLATE_FILE_IMPACTS) { + if (fs.existsSync(path.join(sourceRoot, relativePath))) { + changes.warnings.push(`${path.join(getSourceRootRelative(cwd, sourceRoot), relativePath)} already exists; ${impact}`) + } + } + + for (const relativePath of ['extensionrc.json', 'scripts/publish-extension.mjs', 'README.md']) { + if (fs.existsSync(path.join(cwd, relativePath))) { + changes.warnings.push(`${relativePath} already exists; generated project-level starter file will be skipped`) + } + } +} + +export const applyInitPreflight = ( + cwd: string, + sourceRoot: string, + packageManager: PackageManager, + selectedPackages: InstallablePackage[], + version: string, + options: InitOptions, + changes: InitChanges +): void => { + if (options.agentsOnly) { + changes.preflight.push('agents-only mode: package.json, configs, and template files are skipped') + return + } + + changes.preflight.push(`source root: ${path.relative(cwd, sourceRoot) || '.'}`) + + const existingLockfiles = LOCKFILES.filter(({ file }) => fs.existsSync(path.join(cwd, file))) + if (existingLockfiles.length === 0) { + changes.preflight.push(`lockfile: none; using ${packageManager}`) + } else { + changes.preflight.push(`lockfile: ${existingLockfiles.map(({ file }) => file).join(', ')}; using ${packageManager}`) + } + + if (existingLockfiles.length > 1) { + changes.warnings.push(`Multiple lockfiles found: ${existingLockfiles.map(({ file }) => file).join(', ')}`) + } + + if (!options.target && !options.srcDir && fs.existsSync(path.join(cwd, 'src')) && path.basename(sourceRoot) === 'web') { + changes.warnings.push('src/ already exists; generated frontend source root resolved to web/') + } + + changes.preflight.push(describePathState(cwd, 'src')) + changes.preflight.push(describePathState(cwd, 'web')) + + for (const configFile of CONFIG_FILES) { + if (fs.existsSync(path.join(cwd, configFile))) { + changes.preflight.push(`${configFile}: found; generated config will be skipped unless --force-files is used`) + } + } + + analyzeTsConfig(cwd, sourceRoot, changes) + analyzeViteConfig(cwd, sourceRoot, changes) + analyzeEslintConfig(cwd, changes) + analyzeTemplateFileSkips(cwd, sourceRoot, options, changes) + + if (hasEnabledMcpConfigHook(selectedPackages, options)) { + changes.preflight.push('v1-endpoint init-config: enabled') + + if (options.mcpClientConfigs?.length) { + changes.preflight.push(`MCP client configs requested: ${options.mcpClientConfigs.join(', ')}`) + } + } + + const packageJson = readExistingPackageJson(path.join(cwd, 'package.json'), changes) + if (packageJson) { + analyzePackageJson(packageJson, selectedPackages, version, options, changes) + } +} diff --git a/src/cmd/embed-ui/report.ts b/src/cmd/embed-ui/report.ts new file mode 100644 index 00000000..d9149853 --- /dev/null +++ b/src/cmd/embed-ui/report.ts @@ -0,0 +1,130 @@ +import type { InitChanges } from './types' +import type { InitOptions } from './args' +import type { PackageChange } from './types' +import type { PackageManager } from './args' + +export const createInitChanges = (): InitChanges => ({ + preflight: [], + packageJson: [], + directories: [], + files: [], + agents: [], + mcp: [], + hooks: [], + install: null, + skipped: [], + warnings: [], +}) + +export const printChanges = (changes: PackageChange[]): void => { + for (const change of changes) { + let prefix: string + + if (change.type === 'script') { + prefix = `scripts: ${change.name} -> ${change.nextRange}` + } else if (change.type === 'field') { + prefix = `${change.name} -> ${change.nextRange}` + } else { + prefix = change.type === 'install' + ? `${change.section}: ${change.name} -> ${change.nextRange}` + : `${change.section}: ${change.name} ${change.currentRange} -> ${change.nextRange}` + } + + console.log(` ${prefix}`) + } +} + +export const printInitReport = ( + cwd: string, + sourceRoot: string, + version: string, + packageManager: PackageManager, + changes: InitChanges, + options: InitOptions +): void => { + console.log(`CWD: ${cwd}`) + console.log(`Target: ${sourceRoot}`) + console.log(`Resolved version: ${version}`) + console.log(`Package manager: ${packageManager}`) + + if (changes.preflight.length > 0) { + console.log('') + console.log('preflight') + for (const item of changes.preflight) { + console.log(` ${item}`) + } + } + + if (changes.packageJson.length > 0) { + console.log('') + console.log('package.json') + printChanges(changes.packageJson) + } + + if (changes.directories.length > 0) { + console.log('') + console.log('directories') + for (const directoryPath of changes.directories) { + console.log(` create ${directoryPath}`) + } + } + + if (changes.files.length > 0) { + console.log('') + console.log('files') + for (const filePath of changes.files) { + console.log(` create ${filePath}`) + } + } + + if (changes.agents.length > 0) { + console.log('') + console.log('AGENTS.md') + for (const agentChange of changes.agents) { + console.log(` ${agentChange}`) + } + } + + if (changes.mcp.length > 0) { + console.log('') + console.log('MCP') + for (const mcpChange of changes.mcp) { + console.log(` ${mcpChange}`) + } + } + + if (changes.hooks.length > 0) { + console.log('') + console.log('package hooks') + for (const hook of changes.hooks) { + console.log(` ${options.dryRun ? 'would run' : 'ran'} ${hook}`) + } + } + + if (changes.install) { + console.log('') + console.log('install') + console.log(` ${changes.install}`) + } + + if (changes.skipped.length > 0) { + console.log('') + console.log('skipped') + for (const skipped of changes.skipped) { + console.log(` ${skipped}`) + } + } + + if (changes.warnings.length > 0) { + console.log('') + console.log('warnings') + for (const warning of new Set(changes.warnings)) { + console.log(` ${warning}`) + } + } + + if (options.dryRun) { + console.log('') + console.log('Dry run enabled, no files were modified.') + } +} diff --git a/src/cmd/embed-ui/templates.ts b/src/cmd/embed-ui/templates.ts new file mode 100644 index 00000000..b225d872 --- /dev/null +++ b/src/cmd/embed-ui/templates.ts @@ -0,0 +1,173 @@ +import type { InitOptions } from './args' +import type { PackageManager } from './args' + +import path from 'node:path' + +import { randomUUID } from 'node:crypto' + +import endpointWorkerTemplate from './templates/endpoint.worker.ts.txt?raw' +import envDtsTemplate from './templates/env.d.ts.txt?raw' +import eslintConfigTemplate from './templates/eslint.config.js.txt?raw' +import extensionIconTemplate from './templates/extension.svg.txt?raw' +import i18nIndexTemplate from './templates/i18n-index.ts.txt?raw' +import orderWidgetTemplate from './templates/OrderCommonAfterWidget.vue.txt?raw' +import publishScriptTemplate from './templates/publish-extension.mjs.txt?raw' +import readmeEnGBTemplate from './templates/README.en-GB.md.txt?raw' +import readmeEsESTemplate from './templates/README.es-ES.md.txt?raw' +import readmeRuRUTemplate from './templates/README.ru-RU.md.txt?raw' +import settingsPageTemplate from './templates/SettingsPage.vue.txt?raw' +import tsConfigTemplate from './templates/tsconfig.json.txt?raw' +import viteConfigTemplate from './templates/vite.config.ts.txt?raw' + +import { DEFAULT_NEWLINE } from './package-json' + +const toPosixRelative = (from: string, to: string): string => { + const relativePath = path.relative(from, to) || '.' + + return relativePath.split(path.sep).join('/') +} + +const quoteJsString = (value: string): string => `'${value.replace(/\\/gu, '\\\\').replace(/'/gu, '\\\'')}'` + +const replaceTemplateVars = (template: string, vars: Record): string => { + let content = template + + for (const [key, value] of Object.entries(vars)) { + content = content.replaceAll(`__${key}__`, value) + } + + return content +} + +const readmeTemplates = { + 'en-GB': readmeEnGBTemplate, + 'es-ES': readmeEsESTemplate, + 'ru-RU': readmeRuRUTemplate, +} as const + +type ReadmeLocale = keyof typeof readmeTemplates + +const normalizeLocale = (value: string | undefined): ReadmeLocale | null => { + const normalized = value?.split('.')[0].replace('_', '-').toLowerCase() + + if (!normalized) { + return null + } + + if (normalized.startsWith('ru')) { + return 'ru-RU' + } + + if (normalized.startsWith('es')) { + return 'es-ES' + } + + if (normalized.startsWith('en')) { + return 'en-GB' + } + + return null +} + +const detectReadmeLocale = (): ReadmeLocale => { + const envCandidates = [ + process.env.LANGUAGE?.split(':')[0], + process.env.LC_ALL, + process.env.LC_MESSAGES, + process.env.LANG, + ] + + for (const candidate of envCandidates) { + const locale = normalizeLocale(candidate) + if (locale) { + return locale + } + } + + return 'en-GB' +} + +const createPackageManagerRunCommand = (packageManager: PackageManager): string => { + if (packageManager === 'npm') { + return 'npm run' + } + + if (packageManager === 'bun') { + return 'bun run' + } + + return packageManager +} + +export const createEnvDts = (): string => envDtsTemplate + +export const createTsConfig = (cwd: string, sourceRoot: string): string => replaceTemplateVars( + tsConfigTemplate, + { + SOURCE_ROOT_RELATIVE: toPosixRelative(cwd, sourceRoot), + } +) + +export const createViteConfig = (cwd: string, sourceRoot: string): string => replaceTemplateVars( + viteConfigTemplate, + { + ENTRY_PATH: quoteJsString(toPosixRelative(cwd, path.join(sourceRoot, 'endpoint/endpoint.worker.ts'))), + LOCALE_INCLUDE_PATTERN: toPosixRelative(cwd, path.join(sourceRoot, 'i18n/locales')), + SOURCE_ROOT_PATH: quoteJsString(toPosixRelative(cwd, sourceRoot)), + } +) + +export const createEslintConfig = (cwd: string, sourceRoot: string): string => replaceTemplateVars( + eslintConfigTemplate, + { + LOCALE_DIR_PATTERN: `./${toPosixRelative(cwd, path.join(sourceRoot, 'i18n/locales'))}/*.{json,json5,yaml,yml}`, + } +) + +export const createEndpointWorker = (options: InitOptions): string => replaceTemplateVars( + endpointWorkerTemplate, + { + PAGE_CODE: quoteJsString(options.pageCode), + WIDGET_TARGET: quoteJsString(options.widgetTarget), + } +) + +export const createI18nIndex = (): string => i18nIndexTemplate + +export const createSettingsPage = (): string => settingsPageTemplate + +export const createOrderWidget = (): string => orderWidgetTemplate + +export const createMessages = (): string => `${JSON.stringify({}, null, 2)}${DEFAULT_NEWLINE}` + +export const createExtensionConfig = (options: InitOptions): string => `${JSON.stringify({ + code: 'retailcrm-extension-frontend', + name: 'RetailCRM Extension Frontend', + uuid: randomUUID(), + version: '1.0.0', + targets: [options.widgetTarget], + pages: [options.pageCode], + stylesheet: true, + entrypointType: 'script', + runner: 'worker', +}, null, 2)}${DEFAULT_NEWLINE}` + +export const createExtensionIcon = (): string => extensionIconTemplate + +export const createPublishScript = (): string => publishScriptTemplate + +export const createReadme = ( + cwd: string, + sourceRoot: string, + options: InitOptions, + packageManager: PackageManager +): string => replaceTemplateVars( + readmeTemplates[detectReadmeLocale()], + { + PACKAGE_MANAGER: packageManager, + PACKAGE_MANAGER_RUN: createPackageManagerRunCommand(packageManager), + PAGE_CODE: options.pageCode, + SOURCE_ROOT: toPosixRelative(cwd, sourceRoot), + WIDGET_TARGET: options.widgetTarget, + } +) diff --git a/src/cmd/embed-ui/templates/OrderCommonAfterWidget.vue.txt b/src/cmd/embed-ui/templates/OrderCommonAfterWidget.vue.txt new file mode 100644 index 00000000..43bd2373 --- /dev/null +++ b/src/cmd/embed-ui/templates/OrderCommonAfterWidget.vue.txt @@ -0,0 +1,272 @@ + + + + + +{ + "cancel": "Cancel", + "close": "Close", + "createTask": "Create task after save", + "followUpNote": "Follow-up note", + "openSidebar": "Prepare follow-up", + "openWindow": "Quick action", + "sampleCustomer": "Sample customer", + "sampleCustomerValue": "Maria Garcia, paid order", + "sampleTarget": "Current target", + "save": "Save", + "saveDraft": "Save draft", + "sidebarLead": "Use this sidebar as a compact place for real order controls.", + "sidebarTitle": "Order follow-up", + "windowLead": "Use a modal window for a focused confirmation or a short blocking action.", + "windowTitle": "Quick order action" +} + + + +{ + "cancel": "Cancelar", + "close": "Cerrar", + "createTask": "Crear tarea al guardar", + "followUpNote": "Nota de seguimiento", + "openSidebar": "Preparar seguimiento", + "openWindow": "Accion rapida", + "sampleCustomer": "Cliente de ejemplo", + "sampleCustomerValue": "Maria Garcia, pedido pagado", + "sampleTarget": "Target actual", + "save": "Guardar", + "saveDraft": "Guardar borrador", + "sidebarLead": "Use esta barra lateral como lugar compacto para controles reales del pedido.", + "sidebarTitle": "Seguimiento del pedido", + "windowLead": "Use una ventana modal para una confirmacion enfocada o una accion bloqueante breve.", + "windowTitle": "Accion rapida del pedido" +} + + + +{ + "cancel": "Отменить", + "close": "Закрыть", + "createTask": "Создать задачу после сохранения", + "followUpNote": "Заметка для связи", + "openSidebar": "Подготовить связь", + "openWindow": "Быстрое действие", + "sampleCustomer": "Демонстрационный клиент", + "sampleCustomerValue": "Мария Гарсия, оплаченный заказ", + "sampleTarget": "Текущая цель", + "save": "Сохранить", + "saveDraft": "Сохранить черновик", + "sidebarLead": "Используйте эту боковую панель как компактное место для реальных контролов заказа.", + "sidebarTitle": "Связь по заказу", + "windowLead": "Используйте модальное окно для точечного подтверждения или короткого блокирующего действия.", + "windowTitle": "Быстрое действие с заказом" +} + + + diff --git a/src/cmd/embed-ui/templates/README.en-GB.md.txt b/src/cmd/embed-ui/templates/README.en-GB.md.txt new file mode 100644 index 00000000..1b8ffbae --- /dev/null +++ b/src/cmd/embed-ui/templates/README.en-GB.md.txt @@ -0,0 +1,62 @@ +# RetailCRM extension frontend + +This project was generated by `embed-ui init`. + +## What Was Added + +- `package.json` with scripts for Vite build, ESLint, and extension publishing. +- `extensionrc.json` with the generated extension manifest source. +- `__SOURCE_ROOT__/endpoint/endpoint.worker.ts` with `defineRunner`, one page runner, and one widget runner. +- `__SOURCE_ROOT__/pages/SettingsPage.vue` as a starter settings page. +- `__SOURCE_ROOT__/widgets/OrderCommonAfterWidget.vue` as a starter order widget. +- `__SOURCE_ROOT__/i18n/` with shared JSON message files. +- `scripts/publish-extension.mjs` for creating `dist/extension.zip` and publishing the integration module through RetailCRM API. +- `AGENTS.md` when agent instructions were enabled during init. + +## Replace Generic Values + +Review these generated placeholders before using the project in a real integration: + +- Extension code in `extensionrc.json`: `retailcrm-extension-frontend`. +- Extension name in `extensionrc.json`: `RetailCRM Extension Frontend`. +- Page code: `__PAGE_CODE__`. +- Widget target: `__WIDGET_TARGET__`. +- Sample controls and fake data in `__SOURCE_ROOT__/pages/SettingsPage.vue`. +- Sample toolbar actions and fake order data in `__SOURCE_ROOT__/widgets/OrderCommonAfterWidget.vue`. +- Shared messages in `__SOURCE_ROOT__/i18n/locales/*.json`. + +The generated page and widget are intentionally generic. Keep the structure you need, but replace the sample labels, fields, and fake data with real product behavior. + +## Vue File Names + +`SettingsPage.vue` and `OrderCommonAfterWidget.vue` are generic starter names. In product code, rename Vue files after the role they play in the extension, and update imports in `__SOURCE_ROOT__/endpoint/endpoint.worker.ts`. + +Examples from RetailCRM extension examples: + +- `ReturnsPage.vue` is a full returns-management page. +- `TasksPage.vue` is a task list/workspace page. +- `SummaryPage.vue` is a summary dashboard page. +- `RecordToCalendlyWidget.vue` is a focused widget for one scenario. + +Use the same idea for your code: `LoyaltySettingsPage.vue`, `OrderNotesWidget.vue`, `PaymentStatusSidebar.vue`, or another name that describes the real scenario. + +## Commands + +```bash +__PACKAGE_MANAGER__ install +__PACKAGE_MANAGER_RUN__ eslint +__PACKAGE_MANAGER_RUN__ build +__PACKAGE_MANAGER_RUN__ publish-extension -- --archive-only +``` + +## Publishing + +Create `.env` in the project root when you want `publish-extension` to update RetailCRM: + +```dotenv +CRM_API_HOST=https://example.retailcrm.pro +CRM_API_KEY=your-api-key +MODULE_URL=https://example.com +``` + +Run `__PACKAGE_MANAGER_RUN__ build` before publishing. The archive-only mode creates `dist/extension.zip` without sending API requests. diff --git a/src/cmd/embed-ui/templates/README.es-ES.md.txt b/src/cmd/embed-ui/templates/README.es-ES.md.txt new file mode 100644 index 00000000..d923c93b --- /dev/null +++ b/src/cmd/embed-ui/templates/README.es-ES.md.txt @@ -0,0 +1,62 @@ +# Frontend de extension RetailCRM + +Este proyecto fue generado por `embed-ui init`. + +## Que Se Agrego + +- `package.json` con scripts para Vite build, ESLint y publicacion de la extension. +- `extensionrc.json` con la fuente del manifiesto de la extension. +- `__SOURCE_ROOT__/endpoint/endpoint.worker.ts` con `defineRunner`, un runner de pagina y un runner de widget. +- `__SOURCE_ROOT__/pages/SettingsPage.vue` como pagina inicial de configuracion. +- `__SOURCE_ROOT__/widgets/OrderCommonAfterWidget.vue` como widget inicial del pedido. +- `__SOURCE_ROOT__/i18n/` con archivos JSON de mensajes compartidos. +- `scripts/publish-extension.mjs` para crear `dist/extension.zip` y publicar el modulo de integracion por RetailCRM API. +- `AGENTS.md` si las instrucciones para agentes estaban activadas durante init. + +## Sustituya Los Valores Genericos + +Revise estos valores generados antes de usar el proyecto en una integracion real: + +- Codigo de extension en `extensionrc.json`: `retailcrm-extension-frontend`. +- Nombre de extension en `extensionrc.json`: `RetailCRM Extension Frontend`. +- Codigo de pagina: `__PAGE_CODE__`. +- Target del widget: `__WIDGET_TARGET__`. +- Controles de ejemplo y datos ficticios en `__SOURCE_ROOT__/pages/SettingsPage.vue`. +- Acciones toolbar de ejemplo y datos ficticios del pedido en `__SOURCE_ROOT__/widgets/OrderCommonAfterWidget.vue`. +- Mensajes compartidos en `__SOURCE_ROOT__/i18n/locales/*.json`. + +La pagina y el widget generados son intencionalmente genericos. Mantenga la estructura que necesite, pero sustituya etiquetas, campos y datos ficticios por comportamiento real del producto. + +## Nombres De Archivos Vue + +`SettingsPage.vue` y `OrderCommonAfterWidget.vue` son nombres iniciales genericos. En codigo de producto, renombre los archivos Vue segun la funcion que cumplen en la extension y actualice los imports en `__SOURCE_ROOT__/endpoint/endpoint.worker.ts`. + +Ejemplos del repositorio de extensiones RetailCRM: + +- `ReturnsPage.vue` es una pagina completa de gestion de devoluciones. +- `TasksPage.vue` es una pagina de lista o espacio de trabajo de tareas. +- `SummaryPage.vue` es una pagina de resumen o dashboard. +- `RecordToCalendlyWidget.vue` es un widget enfocado en un escenario. + +Use la misma idea para su codigo: `LoyaltySettingsPage.vue`, `OrderNotesWidget.vue`, `PaymentStatusSidebar.vue` u otro nombre que describa el escenario real. + +## Comandos + +```bash +__PACKAGE_MANAGER__ install +__PACKAGE_MANAGER_RUN__ eslint +__PACKAGE_MANAGER_RUN__ build +__PACKAGE_MANAGER_RUN__ publish-extension -- --archive-only +``` + +## Publicacion + +Cree `.env` en la raiz del proyecto cuando quiera que `publish-extension` actualice RetailCRM: + +```dotenv +CRM_API_HOST=https://example.retailcrm.pro +CRM_API_KEY=your-api-key +MODULE_URL=https://example.com +``` + +Ejecute `__PACKAGE_MANAGER_RUN__ build` antes de publicar. El modo archive-only crea `dist/extension.zip` sin enviar peticiones API. diff --git a/src/cmd/embed-ui/templates/README.ru-RU.md.txt b/src/cmd/embed-ui/templates/README.ru-RU.md.txt new file mode 100644 index 00000000..abffca1e --- /dev/null +++ b/src/cmd/embed-ui/templates/README.ru-RU.md.txt @@ -0,0 +1,62 @@ +# Фронтенд расширения RetailCRM + +Проект создан командой `embed-ui init`. + +## Что Добавлено + +- `package.json` со скриптами для сборки Vite, ESLint и публикации расширения. +- `extensionrc.json` с исходным описанием манифеста расширения. +- `__SOURCE_ROOT__/endpoint/endpoint.worker.ts` с `defineRunner`, одним runner страницы и одним runner виджета. +- `__SOURCE_ROOT__/pages/SettingsPage.vue` как стартовая страница настроек. +- `__SOURCE_ROOT__/widgets/OrderCommonAfterWidget.vue` как стартовый виджет заказа. +- `__SOURCE_ROOT__/i18n/` с общими JSON-файлами переводов. +- `scripts/publish-extension.mjs` для создания `dist/extension.zip` и публикации интеграционного модуля через RetailCRM API. +- `AGENTS.md`, если при инициализации были включены инструкции для агентов. + +## Замените Generic Значения + +Перед использованием проекта в реальной интеграции проверьте сгенерированные общие значения: + +- Код расширения в `extensionrc.json`: `retailcrm-extension-frontend`. +- Название расширения в `extensionrc.json`: `RetailCRM Extension Frontend`. +- Код страницы: `__PAGE_CODE__`. +- Цель виджета: `__WIDGET_TARGET__`. +- Демонстрационные контролы и ненастоящие данные в `__SOURCE_ROOT__/pages/SettingsPage.vue`. +- Демонстрационные toolbar-действия и ненастоящие данные заказа в `__SOURCE_ROOT__/widgets/OrderCommonAfterWidget.vue`. +- Общие сообщения в `__SOURCE_ROOT__/i18n/locales/*.json`. + +Сгенерированные страница и виджет намеренно сделаны универсальными. Оставьте нужную структуру, но замените примерные подписи, поля и ненастоящие данные на реальное поведение продукта. + +## Имена Vue-Файлов + +`SettingsPage.vue` и `OrderCommonAfterWidget.vue` — универсальные стартовые имена. В продуктовом коде переименуйте Vue-файлы по роли, которую они выполняют в расширении, и обновите импорты в `__SOURCE_ROOT__/endpoint/endpoint.worker.ts`. + +Примеры из репозитория расширений RetailCRM: + +- `ReturnsPage.vue` — полноценная страница управления возвратами. +- `TasksPage.vue` — страница списка задач или рабочей области задач. +- `SummaryPage.vue` — страница сводки или дашборда. +- `RecordToCalendlyWidget.vue` — сфокусированный виджет под один сценарий. + +Используйте тот же принцип: `LoyaltySettingsPage.vue`, `OrderNotesWidget.vue`, `PaymentStatusSidebar.vue` или другое имя, которое описывает реальный сценарий. + +## Команды + +```bash +__PACKAGE_MANAGER__ install +__PACKAGE_MANAGER_RUN__ eslint +__PACKAGE_MANAGER_RUN__ build +__PACKAGE_MANAGER_RUN__ publish-extension -- --archive-only +``` + +## Публикация + +Создайте `.env` в корне проекта, когда потребуется обновлять RetailCRM через `publish-extension`: + +```dotenv +CRM_API_HOST=https://example.retailcrm.pro +CRM_API_KEY=your-api-key +MODULE_URL=https://example.com +``` + +Перед публикацией выполните `__PACKAGE_MANAGER_RUN__ build`. Режим archive-only создает `dist/extension.zip` без API-запросов. diff --git a/src/cmd/embed-ui/templates/SettingsPage.vue.txt b/src/cmd/embed-ui/templates/SettingsPage.vue.txt new file mode 100644 index 00000000..51160d76 --- /dev/null +++ b/src/cmd/embed-ui/templates/SettingsPage.vue.txt @@ -0,0 +1,303 @@ + + + + + +{ + "assistantName": "Assistant name", + "assistantNameHint": "Use this value as a starter label for your real setting.", + "enabled": "Enable order prompts", + "hint": "Hint", + "note": "Default note", + "owner": "Responsible team", + "ownerDelivery": "Delivery team", + "ownerSales": "Sales team", + "save": "Save", + "saved": "Settings saved", + "subtitle": "Starter configuration page", + "title": "Extension settings", + "workspaceDescription": "Replace these sample controls with settings that drive your embedded page and order widget.", + "workspaceTitle": "Order workflow defaults" +} + + + +{ + "assistantName": "Nombre del asistente", + "assistantNameHint": "Use este valor como etiqueta inicial para su ajuste real.", + "enabled": "Activar sugerencias del pedido", + "hint": "Ayuda", + "note": "Nota predeterminada", + "owner": "Equipo responsable", + "ownerDelivery": "Equipo de entrega", + "ownerSales": "Equipo comercial", + "save": "Guardar", + "saved": "Configuracion guardada", + "subtitle": "Pagina inicial de configuracion", + "title": "Configuracion de la extension", + "workspaceDescription": "Sustituya estos controles de ejemplo por ajustes que controlen su pagina integrada y el widget del pedido.", + "workspaceTitle": "Valores iniciales del proceso de pedidos" +} + + + +{ + "assistantName": "Название помощника", + "assistantNameHint": "Используйте это значение как стартовую подпись для реальной настройки.", + "enabled": "Включить подсказки в заказе", + "hint": "Подсказка", + "note": "Заметка по умолчанию", + "owner": "Ответственная команда", + "ownerDelivery": "Команда доставки", + "ownerSales": "Отдел продаж", + "save": "Сохранить", + "saved": "Настройки сохранены", + "subtitle": "Стартовая страница настроек", + "title": "Настройки расширения", + "workspaceDescription": "Замените эти демонстрационные контролы настройками, которые управляют встроенной страницей и виджетом заказа.", + "workspaceTitle": "Настройки сценария заказа" +} + + + diff --git a/src/cmd/embed-ui/templates/endpoint.worker.ts.txt b/src/cmd/embed-ui/templates/endpoint.worker.ts.txt new file mode 100644 index 00000000..d0c3d2af --- /dev/null +++ b/src/cmd/embed-ui/templates/endpoint.worker.ts.txt @@ -0,0 +1,47 @@ +import type { App } from 'vue' + +import { watch } from 'vue' + +import { useField } from '@retailcrm/embed-ui' + +import { + definePageRunner, + defineRunner, + defineWidgetRunner, + runEndpoint, +} from '@retailcrm/embed-ui-v1-endpoint/remote' +import { + useContext as useSettingsContext, +} from '@retailcrm/embed-ui-v1-contexts/remote/settings' + +import OrderCommonAfterWidget from '../widgets/OrderCommonAfterWidget.vue' + +import SettingsPage from '../pages/SettingsPage.vue' + +import { i18n } from '../i18n' + +const setupApp = async (app: App) => { + app.use(i18n) + + const settings = useSettingsContext() + await settings.initialize() + + const locale = useField(settings, 'system.locale') + + i18n.global.locale.value = locale.value + + watch(locale, value => { + i18n.global.locale.value = value + }) +} + +const runner = defineRunner({ + pages: [{ + __PAGE_CODE__: definePageRunner(SettingsPage, setupApp), + }], + widgets: [{ + __WIDGET_TARGET__: defineWidgetRunner(OrderCommonAfterWidget, setupApp), + }], +}) + +runEndpoint(runner) diff --git a/src/cmd/embed-ui/templates/env.d.ts.txt b/src/cmd/embed-ui/templates/env.d.ts.txt new file mode 100644 index 00000000..20287646 --- /dev/null +++ b/src/cmd/embed-ui/templates/env.d.ts.txt @@ -0,0 +1,15 @@ +/// + +declare module '*.svg' { + import type { DefineComponent } from 'vue' + + const component: DefineComponent, Record, unknown> + export default component +} + +declare module '*.vue' { + import type { DefineComponent } from 'vue' + + const component: DefineComponent, Record, unknown> + export default component +} diff --git a/src/cmd/embed-ui/templates/eslint.config.js.txt b/src/cmd/embed-ui/templates/eslint.config.js.txt new file mode 100644 index 00000000..91dabd73 --- /dev/null +++ b/src/cmd/embed-ui/templates/eslint.config.js.txt @@ -0,0 +1,167 @@ +import { defineConfig } from 'eslint/config' + +import globals from 'globals' + +import pluginDependencies from '@omnicajs/eslint-plugin-dependencies' +import pluginJs from '@eslint/js' +import pluginTs from 'typescript-eslint' +import pluginVue from 'eslint-plugin-vue' +import pluginVueI18n from '@intlify/eslint-plugin-vue-i18n' + +export default defineConfig([ + { files: ['**/*.{js,mjs,cjs,ts,vue}'] }, + { + settings: { + 'vue-i18n': { + localeDir: { + pattern: '__LOCALE_DIR_PATTERN__', + localeKey: 'file', + }, + messageSyntaxVersion: '^11.0.0', + }, + }, + }, + pluginJs.configs.recommended, + ...pluginTs.configs.recommended, + ...pluginVue.configs['flat/essential'], + ...pluginVueI18n.configs.recommended, + { + files: ['**/*.{js,mjs,cjs,ts,vue}'], + plugins: { + '@intlify/vue-i18n': pluginVueI18n, + dependencies: pluginDependencies, + }, + languageOptions: { + globals: { + ...globals.browser, + ...globals.node, + }, + }, + rules: { + 'comma-dangle': ['error', 'always-multiline'], + 'eqeqeq': ['error', 'always'], + 'indent': ['error', 2, { SwitchCase: 1 }], + 'no-debugger': 'error', + 'no-multiple-empty-lines': ['error', { max: 1, maxBOF: 0, maxEOF: 0 }], + 'no-trailing-spaces': 'error', + 'object-curly-spacing': ['error', 'always'], + 'quotes': ['error', 'single'], + 'semi': ['error', 'never'], + + '@typescript-eslint/consistent-type-imports': ['error', { + prefer: 'type-imports', + fixStyle: 'separate-type-imports', + }], + + '@intlify/vue-i18n/key-format-style': ['error', 'camelCase', { + allowArray: true, + }], + '@intlify/vue-i18n/no-duplicate-keys-in-locale': 'error', + '@intlify/vue-i18n/no-dynamic-keys': 'error', + '@intlify/vue-i18n/no-missing-keys': 'error', + '@intlify/vue-i18n/no-missing-keys-in-other-locales': 'error', + '@intlify/vue-i18n/no-raw-text': ['warn', { + ignorePattern: '^[-–—~+#:()&=×%/\\d\\s\\u00A0\\n,.<>•]+$', + ignoreText: ['API', 'CRM', ''], + }], + '@intlify/vue-i18n/no-unknown-locale': 'error', + '@intlify/vue-i18n/no-unused-keys': 'error', + '@intlify/vue-i18n/sfc-locale-attr': 'error', + + 'dependencies/import-style': ['error', { + maxSingleLineLength: 90, + maxSingleLineSpecifiers: 3, + }], + 'dependencies/separate-type-imports': 'error', + 'dependencies/separate-type-partitions': 'error', + 'dependencies/sort-named-imports': ['error', { + type: 'alphabetical', + ignoreAlias: true, + }], + 'dependencies/sort-imports': ['error', { + type: 'alphabetical', + imports: { + orderBy: 'alias', + splitDeclarations: true, + }, + groups: [ + 'side-effect-style', + 'side-effect', + [ + 'type-import', + 'type-external', + 'type-vue-components', + 'type-internal', + 'type-parent', + 'type-sibling', + 'type-index', + ], + 'builtin', + 'value-external', + 'value-vue-components', + 'value-internal', + ['value-parent', 'value-sibling'], + 'index', + 'ts-equals-import', + 'unknown', + ], + customGroups: [{ + groupName: 'type-vue-components', + selector: 'type', + elementNamePattern: ['\\.(svg|vue)$'], + }, { + groupName: 'value-vue-components', + elementNamePattern: ['\\.(svg|vue)$'], + }], + newlinesInside: 1, + partitions: { + orderBy: 'type-first', + splitBy: { + comments: false, + newlines: true, + }, + }, + }], + }, + }, + { + files: ['**/*.vue'], + languageOptions: { + parserOptions: { parser: pluginTs.parser }, + }, + rules: { + 'vue/block-order': ['error', { + order: ['template', 'script', 'i18n', 'style'], + }], + 'vue/attributes-order': 'error', + 'vue/component-definition-name-casing': ['error', 'PascalCase'], + 'vue/component-name-in-template-casing': ['error', 'PascalCase'], + 'vue/html-indent': ['error', 4, { + attribute: 1, + baseIndent: 1, + closeBracket: 0, + switchCase: 1, + }], + 'vue/html-self-closing': ['error', { + html: { + component: 'always', + normal: 'always', + void: 'always', + }, + math: 'always', + svg: 'always', + }], + 'vue/max-attributes-per-line': ['error', { + singleline: 4, + multiline: { max: 1 }, + }], + 'vue/script-indent': ['error', 2, { + baseIndent: 0, + switchCase: 1, + }], + + 'indent': 'off', + }, + }, + { ignores: ['dist/**', 'coverage/**'] }, +]) diff --git a/src/cmd/embed-ui/templates/extension.svg.txt b/src/cmd/embed-ui/templates/extension.svg.txt new file mode 100644 index 00000000..b99ee947 --- /dev/null +++ b/src/cmd/embed-ui/templates/extension.svg.txt @@ -0,0 +1,4 @@ + + + + diff --git a/src/cmd/embed-ui/templates/i18n-index.ts.txt b/src/cmd/embed-ui/templates/i18n-index.ts.txt new file mode 100644 index 00000000..7c2ace13 --- /dev/null +++ b/src/cmd/embed-ui/templates/i18n-index.ts.txt @@ -0,0 +1,21 @@ +import { createI18n } from 'vue-i18n' + +import enGB from './locales/en-GB.json' +import esES from './locales/es-ES.json' +import ruRU from './locales/ru-RU.json' + +const messages = { + 'en-GB': enGB, + 'es-ES': esES, + 'ru-RU': ruRU, +} as const + +export type Locale = keyof typeof messages +export type MessageSchema = typeof enGB + +export const i18n = createI18n<[MessageSchema], Locale>({ + legacy: false, + locale: 'ru-RU', + fallbackLocale: 'en-GB', + messages, +}) diff --git a/src/cmd/embed-ui/templates/publish-extension.mjs.txt b/src/cmd/embed-ui/templates/publish-extension.mjs.txt new file mode 100644 index 00000000..7476fb9d --- /dev/null +++ b/src/cmd/embed-ui/templates/publish-extension.mjs.txt @@ -0,0 +1,287 @@ +#!/usr/bin/env node + +import { fileURLToPath } from 'node:url' + +import fs from 'node:fs' + +import path from 'node:path' + +import { spawnSync } from 'node:child_process' + +const scriptDir = path.dirname(fileURLToPath(import.meta.url)) +const projectRoot = path.resolve(scriptDir, '..') +const args = new Set(process.argv.slice(2)) +const archiveOnly = args.has('--archive-only') + +const readJsonFile = (filePath) => JSON.parse(fs.readFileSync(filePath, 'utf8')) + +const loadEnvFile = (filePath) => { + if (!fs.existsSync(filePath)) { + return + } + + for (const line of fs.readFileSync(filePath, 'utf8').split(/\r?\n/u)) { + const trimmed = line.trim() + + if (!trimmed || trimmed.startsWith('#')) { + continue + } + + const separatorIndex = trimmed.indexOf('=') + + if (separatorIndex === -1) { + continue + } + + const key = trimmed.slice(0, separatorIndex).trim() + let value = trimmed.slice(separatorIndex + 1).trim() + + if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith('\'') && value.endsWith('\''))) { + value = value.slice(1, -1) + } + + process.env[key] ??= value + } +} + +const assertNonEmptyString = (value, field) => { + if (typeof value !== 'string' || value.trim() === '') { + throw new Error('Field "' + field + '" must be a non-empty string') + } + + return value +} + +const assertStringArray = (value, field) => { + if (value === undefined) { + return [] + } + + if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || item.trim() === '')) { + throw new Error('Field "' + field + '" must be an array of non-empty strings') + } + + return value +} + +const listFiles = (directoryPath, basePath = directoryPath) => { + const result = [] + + for (const entry of fs.readdirSync(directoryPath, { withFileTypes: true })) { + const entryPath = path.join(directoryPath, entry.name) + const relativePath = path.relative(basePath, entryPath).split(path.sep).join('/') + + if (entry.isDirectory()) { + result.push(...listFiles(entryPath, basePath)) + continue + } + + if (entry.isFile()) { + result.push(relativePath) + } + } + + return result +} + +const normalizeManifestPath = (value) => typeof value === 'string' && value.startsWith('./') + ? value.slice(2) + : value + +const pickBuildArtifacts = (distDir, code) => { + const files = listFiles(distDir) + .filter(file => file !== 'manifest.json') + .filter(file => file !== code + '.zip') + .filter(file => !file.endsWith('.map')) + + const viteManifestPath = path.join(distDir, '.vite/manifest.json') + + if (fs.existsSync(viteManifestPath)) { + const viteManifest = readJsonFile(viteManifestPath) + const entries = Object.values(viteManifest) + const entry = entries.find(item => item && item.isEntry) ?? entries[0] + + if (entry?.file) { + return { + files, + scriptFile: normalizeManifestPath(entry.file), + styleFile: Array.isArray(entry.css) ? normalizeManifestPath(entry.css[0]) : null, + } + } + } + + return { + files, + scriptFile: files.find(file => file.endsWith('.js')) ?? null, + styleFile: files.find(file => file.endsWith('.css')) ?? null, + } +} + +const zipExtension = (distDir, code, extensionManifest, files) => { + const archivePath = path.join(distDir, 'extension.zip') + const manifestPath = path.join(distDir, 'manifest.json') + const previousManifest = fs.existsSync(manifestPath) ? fs.readFileSync(manifestPath) : null + + fs.writeFileSync(manifestPath, JSON.stringify(extensionManifest), 'utf8') + + try { + const zipResult = spawnSync('zip', ['-rFS', archivePath, ...files, 'manifest.json'], { + cwd: distDir, + stdio: 'inherit', + }) + + if (zipResult.error) { + throw new Error('Zip command failed: ' + zipResult.error.message) + } + + if (zipResult.status !== 0) { + throw new Error('Zip archive creation failed') + } + } finally { + if (previousManifest) { + fs.writeFileSync(manifestPath, previousManifest) + } else { + fs.rmSync(manifestPath, { force: true }) + } + } + + return archivePath +} + +loadEnvFile(path.join(projectRoot, '.env')) + +const configPath = path.join(projectRoot, 'extensionrc.json') + +if (!fs.existsSync(configPath)) { + console.error('Config not found: ' + configPath) + process.exit(1) +} + +let config + +try { + config = readJsonFile(configPath) +} catch (error) { + console.error('Cannot read extensionrc.json:', error) + process.exit(1) +} + +try { + const code = config.code ?? 'retailcrm-extension-frontend' + const uuid = assertNonEmptyString(config.uuid, 'uuid') + const version = assertNonEmptyString(config.version, 'version') + const targets = assertStringArray(config.targets, 'targets') + const pages = assertStringArray(config.pages, 'pages') + const runner = config.runner ?? 'worker' + + if (targets.length === 0 && pages.length === 0) { + throw new Error('Specify at least one target or page in extensionrc.json') + } + + const distDir = path.join(projectRoot, 'dist') + + if (!fs.existsSync(distDir)) { + throw new Error('Build directory not found: ' + distDir) + } + + const { files, scriptFile, styleFile } = pickBuildArtifacts(distDir, code) + + if (!scriptFile) { + throw new Error('Missing JS build artifact. Run npm run build before publishing.') + } + + const extensionManifest = { + code, + version, + entrypoint: scriptFile, + scripts: [scriptFile], + runner, + } + + if (targets.length > 0) { + extensionManifest.targets = targets + } + + if (pages.length > 0) { + extensionManifest.pages = pages + } + + if (styleFile) { + extensionManifest.stylesheet = styleFile + } + + const archivePath = zipExtension(distDir, code, extensionManifest, files) + + console.log('Archive created: ' + archivePath) + + if (archiveOnly) { + process.exit(0) + } + + const crmHost = process.env.CRM_API_HOST + const crmKey = process.env.CRM_API_KEY + const baseUrl = config.baseUrl || process.env.MODULE_URL || process.env.EXTENSION_BASE_URL + + if (!crmHost || !crmKey) { + throw new Error('Missing CRM_API_HOST or CRM_API_KEY in .env') + } + + if (!baseUrl) { + throw new Error('Missing MODULE_URL or EXTENSION_BASE_URL in .env or baseUrl in extensionrc.json') + } + + const embedJs = { + entrypoint: config.entrypoint || '/extension/' + uuid + '/script', + runner, + } + + if (targets.length > 0) { + embedJs.targets = targets + } + + if (pages.length > 0) { + embedJs.pages = pages + } + + if (styleFile && config.stylesheet !== false) { + embedJs.stylesheet = typeof config.stylesheet === 'string' + ? config.stylesheet + : '/extension/' + uuid + '/stylesheet' + } + + const integrationModule = { + code, + integrationCode: code, + active: true, + name: config.name || code, + clientId: config.clientId || 'client-id-xxx', + baseUrl, + integrations: { + embedJs, + }, + } + + const form = new FormData() + form.append('integrationModule', JSON.stringify(integrationModule)) + + const response = await fetch(new URL('/api/v5/integration-modules/' + code + '/edit', crmHost), { + method: 'POST', + headers: { + 'X-Api-Key': crmKey, + }, + body: form, + }) + + const text = await response.text() + + if (!response.ok) { + console.error('Request failed: ' + response.status + ' ' + response.statusText) + console.error(text) + process.exit(1) + } + + console.log(text) +} catch (error) { + console.error(error instanceof Error ? error.message : error) + process.exit(1) +} diff --git a/src/cmd/embed-ui/templates/tsconfig.json.txt b/src/cmd/embed-ui/templates/tsconfig.json.txt new file mode 100644 index 00000000..fc3be2e9 --- /dev/null +++ b/src/cmd/embed-ui/templates/tsconfig.json.txt @@ -0,0 +1,30 @@ +{ + "compilerOptions": { + "target": "ES2022", + "useDefineForClassFields": true, + "module": "ESNext", + "moduleResolution": "Bundler", + "strict": true, + "jsx": "preserve", + "resolveJsonModule": true, + "isolatedModules": true, + "skipLibCheck": true, + "allowSyntheticDefaultImports": true, + "esModuleInterop": true, + "baseUrl": ".", + "paths": { + "@/*": [ + "__SOURCE_ROOT_RELATIVE__/*" + ] + } + }, + "include": [ + "__SOURCE_ROOT_RELATIVE__/**/*", + "env.d.ts" + ], + "vueCompilerOptions": { + "plugins": [ + "@omnicajs/vue-remote/tooling" + ] + } +} diff --git a/src/cmd/embed-ui/templates/vite.config.ts.txt b/src/cmd/embed-ui/templates/vite.config.ts.txt new file mode 100644 index 00000000..b9269006 --- /dev/null +++ b/src/cmd/embed-ui/templates/vite.config.ts.txt @@ -0,0 +1,38 @@ +import { fileURLToPath } from 'node:url' + +import path from 'node:path' + +import { defineConfig } from 'vite' + +import vue from '@vitejs/plugin-vue' +import vueRemoteVitePlugin from '@omnicajs/vue-remote/vite-plugin' + +import vueI18n from '@intlify/unplugin-vue-i18n/vite' + +import svgLoader from 'vite-svg-loader' + +const root = path.dirname(fileURLToPath(import.meta.url)) + +export default defineConfig({ + plugins: [ + svgLoader({ + defaultImport: 'component', + }), + vueRemoteVitePlugin(), + vue(), + vueI18n({ + defaultSFCLang: 'json', + include: path.resolve(root, '__LOCALE_INCLUDE_PATTERN__/**/*.{json,json5,yaml,yml}'), + }), + ], + resolve: { + alias: { + '@': path.resolve(root, __SOURCE_ROOT_PATH__), + }, + }, + build: { + rollupOptions: { + input: path.resolve(root, __ENTRY_PATH__), + }, + }, +}) diff --git a/src/cmd/embed-ui/types.ts b/src/cmd/embed-ui/types.ts new file mode 100644 index 00000000..b541c495 --- /dev/null +++ b/src/cmd/embed-ui/types.ts @@ -0,0 +1,61 @@ +import type { InitOptions } from './args' + +export const TARGET_SECTIONS = [ + 'dependencies', + 'devDependencies', + 'peerDependencies', + 'optionalDependencies', +] as const + +export type DependencySection = typeof TARGET_SECTIONS[number] +export type PackageJson = Record + +export interface Formatting { + indent: string; + newline: string; + trailingNewline: boolean; +} + +export interface InstallablePackage { + id: string; + name: string; + section: DependencySection; + description: string; + hooks?: InstallablePackageHook[]; +} + +export interface InstallablePackageHook { + type: 'agents' | 'config'; + binName: string; + command: 'init-agents' | 'init-config'; + failureMode: 'advisory' | 'required'; + requiresMcp?: boolean; +} + +export interface PackageChange { + type: 'field' | 'install' | 'script' | 'update'; + section?: DependencySection; + name: string; + currentRange?: string | null; + nextRange: string; +} + +export interface InitChanges { + preflight: string[]; + packageJson: PackageChange[]; + directories: string[]; + files: string[]; + agents: string[]; + mcp: string[]; + hooks: string[]; + install: string | null; + skipped: string[]; + warnings: string[]; +} + +export type InitFileWriter = ( + filePath: string, + content: string, + options: InitOptions, + changes: InitChanges +) => boolean diff --git a/src/index.ts b/src/index.ts index f7bbfd07..09017b3b 100644 --- a/src/index.ts +++ b/src/index.ts @@ -70,7 +70,7 @@ export const createWidgetEndpoint = ( async run (channel: Channel, target: WidgetTarget) { retain(channel) - const root = await mountEndpointRoot(channel) + const root = (await mountEndpointRoot(channel)) as Parameters[0] const { createApp } = createRemoteRenderer(root) diff --git a/src/shims-raw.d.ts b/src/shims-raw.d.ts new file mode 100644 index 00000000..57d00c0d --- /dev/null +++ b/src/shims-raw.d.ts @@ -0,0 +1,5 @@ +declare module '*?raw' { + const content: string + + export default content +} diff --git a/tests/embed-ui-update.test.ts b/tests/embed-ui-update.test.ts deleted file mode 100644 index ec0444eb..00000000 --- a/tests/embed-ui-update.test.ts +++ /dev/null @@ -1,137 +0,0 @@ -// @vitest-environment node - -import fs from 'node:fs' -import os from 'node:os' -import path from 'node:path' - -import { - afterEach, - describe, - expect, - test, - vi, -} from 'vitest' - -import { parseArgs, runAdd, runUpdate } from '../bin/embed-ui-update.mjs' - -const createTempDir = () => fs.mkdtempSync(path.join(os.tmpdir(), 'embed-ui-update-')) - -const writeFile = (filePath: string, content: string) => { - fs.mkdirSync(path.dirname(filePath), { recursive: true }) - fs.writeFileSync(filePath, content, 'utf8') -} - -describe('embed-ui update CLI', () => { - afterEach(() => { - vi.restoreAllMocks() - }) - - test('updates package.json files in the whole subtree and preserves indentation', () => { - const tempDir = createTempDir() - const rootPackageJsonPath = path.join(tempDir, 'package.json') - const nestedPackageJsonPath = path.join(tempDir, 'packages/app/package.json') - const ignoredPackageJsonPath = path.join(tempDir, 'node_modules/ignored/package.json') - - writeFile(rootPackageJsonPath, [ - '{', - '\t"name": "root-app",', - '\t"dependencies": {', - '\t\t"@retailcrm/embed-ui-v1-components": "^0.9.0"', - '\t}', - '}', - '', - ].join('\n')) - - writeFile(nestedPackageJsonPath, [ - '{', - ' "name": "nested-app",', - ' "dependencies": {', - ' "@retailcrm/embed-ui-v1-contexts": "~0.8.0"', - ' }', - '}', - '', - ].join('\n')) - - writeFile(ignoredPackageJsonPath, [ - '{', - ' "name": "ignored",', - ' "dependencies": {', - ' "@retailcrm/embed-ui-v1-types": "^0.1.0"', - ' }', - '}', - '', - ].join('\n')) - - vi.spyOn(console, 'log').mockImplementation(() => undefined) - - runUpdate({ - target: tempDir, - version: '1.2.3', - dryRun: false, - exact: false, - add: false, - packages: null, - }) - - expect(fs.readFileSync(rootPackageJsonPath, 'utf8')).toContain( - '\t\t"@retailcrm/embed-ui-v1-components": "^1.2.3"' - ) - expect(fs.readFileSync(nestedPackageJsonPath, 'utf8')).toContain( - ' "@retailcrm/embed-ui-v1-contexts": "~1.2.3"' - ) - expect(fs.readFileSync(ignoredPackageJsonPath, 'utf8')).toContain( - '"@retailcrm/embed-ui-v1-types": "^0.1.0"' - ) - }) - - test('add mode updates only the target package.json and preserves CRLF', async () => { - const tempDir = createTempDir() - const packageJsonPath = path.join(tempDir, 'package.json') - const nestedPackageJsonPath = path.join(tempDir, 'packages/app/package.json') - - writeFile( - packageJsonPath, - '{\r\n "name": "add-app"\r\n}\r\n' - ) - - writeFile( - nestedPackageJsonPath, - '{\n "name": "nested-app"\n}\n' - ) - - vi.spyOn(console, 'log').mockImplementation(() => undefined) - - await runAdd({ - target: tempDir, - version: '2.0.0', - dryRun: false, - exact: false, - add: true, - packages: ['components', 'testing'], - }) - - const updatedPackageJson = fs.readFileSync(packageJsonPath, 'utf8') - - expect(updatedPackageJson.includes('\r\n')).toBe(true) - expect(updatedPackageJson).toBe([ - '{', - ' "name": "add-app",', - ' "dependencies": {', - ' "@retailcrm/embed-ui-v1-components": "^2.0.0"', - ' },', - ' "devDependencies": {', - ' "@retailcrm/embed-ui-v1-testing": "^2.0.0"', - ' }', - '}', - '', - ].join('\r\n')) - - expect(fs.readFileSync(nestedPackageJsonPath, 'utf8')).toBe('{\n "name": "nested-app"\n}\n') - }) - - test('parseArgs rejects --packages without --add', () => { - expect(() => parseArgs(['--packages', 'components'])).toThrow( - 'Option --packages can only be used together with --add' - ) - }) -}) diff --git a/tests/embed-ui.test.ts b/tests/embed-ui.test.ts new file mode 100644 index 00000000..837a039f --- /dev/null +++ b/tests/embed-ui.test.ts @@ -0,0 +1,761 @@ +// @vitest-environment node + +import { execFileSync } from 'node:child_process' +import fs from 'node:fs' +import os from 'node:os' +import path from 'node:path' + +import { + afterEach, + describe, + expect, + test, + vi, +} from 'vitest' + +import { parseArgs, parseInitArgs } from '../src/cmd/embed-ui' +import { resolvePackageHookCommand } from '../src/cmd/embed-ui/package-hook-runner' +import { runAdd, runInit, runUpdate } from '../src/cmd/embed-ui' + +const createTempDir = () => fs.mkdtempSync(path.join(os.tmpdir(), 'embed-ui-')) + +const writeFile = (filePath: string, content: string) => { + fs.mkdirSync(path.dirname(filePath), { recursive: true }) + fs.writeFileSync(filePath, content, 'utf8') +} + +const readJsonFile = (filePath: string): T => + JSON.parse(fs.readFileSync(filePath, 'utf8')) as T + +describe('embed-ui CLI', () => { + afterEach(() => { + vi.restoreAllMocks() + vi.unstubAllEnvs() + }) + + test('updates package.json files in the whole subtree and preserves indentation', () => { + const tempDir = createTempDir() + const rootPackageJsonPath = path.join(tempDir, 'package.json') + const nestedPackageJsonPath = path.join(tempDir, 'packages/app/package.json') + const ignoredPackageJsonPath = path.join(tempDir, 'node_modules/ignored/package.json') + + writeFile(rootPackageJsonPath, [ + '{', + '\t"name": "root-app",', + '\t"dependencies": {', + '\t\t"@retailcrm/embed-ui-v1-components": "^0.9.0"', + '\t}', + '}', + '', + ].join('\n')) + + writeFile(nestedPackageJsonPath, [ + '{', + ' "name": "nested-app",', + ' "dependencies": {', + ' "@retailcrm/embed-ui-v1-contexts": "~0.8.0"', + ' }', + '}', + '', + ].join('\n')) + + writeFile(ignoredPackageJsonPath, [ + '{', + ' "name": "ignored",', + ' "dependencies": {', + ' "@retailcrm/embed-ui-v1-types": "^0.1.0"', + ' }', + '}', + '', + ].join('\n')) + + vi.spyOn(console, 'log').mockImplementation(() => undefined) + + runUpdate({ + command: 'update', + target: tempDir, + version: '1.2.3', + dryRun: false, + exact: false, + add: false, + packages: null, + }) + + expect(fs.readFileSync(rootPackageJsonPath, 'utf8')).toContain( + '\t\t"@retailcrm/embed-ui-v1-components": "^1.2.3"' + ) + expect(fs.readFileSync(nestedPackageJsonPath, 'utf8')).toContain( + ' "@retailcrm/embed-ui-v1-contexts": "~1.2.3"' + ) + expect(fs.readFileSync(ignoredPackageJsonPath, 'utf8')).toContain( + '"@retailcrm/embed-ui-v1-types": "^0.1.0"' + ) + }) + + test('add mode updates only the target package.json and preserves CRLF', async () => { + const tempDir = createTempDir() + const packageJsonPath = path.join(tempDir, 'package.json') + const nestedPackageJsonPath = path.join(tempDir, 'packages/app/package.json') + + writeFile( + packageJsonPath, + '{\r\n "name": "add-app"\r\n}\r\n' + ) + + writeFile( + nestedPackageJsonPath, + '{\n "name": "nested-app"\n}\n' + ) + + vi.spyOn(console, 'log').mockImplementation(() => undefined) + + await runAdd({ + command: 'update', + target: tempDir, + version: '2.0.0', + dryRun: false, + exact: false, + add: true, + packages: ['components', 'testing'], + }) + + const updatedPackageJson = fs.readFileSync(packageJsonPath, 'utf8') + + expect(updatedPackageJson.includes('\r\n')).toBe(true) + expect(updatedPackageJson).toBe([ + '{', + ' "name": "add-app",', + ' "dependencies": {', + ' "@retailcrm/embed-ui-v1-components": "^2.0.0"', + ' },', + ' "devDependencies": {', + ' "@retailcrm/embed-ui-v1-testing": "^2.0.0"', + ' }', + '}', + '', + ].join('\r\n')) + + expect(fs.readFileSync(nestedPackageJsonPath, 'utf8')).toBe('{\n "name": "nested-app"\n}\n') + }) + + test('parseArgs rejects --packages without --add', () => { + expect(() => parseArgs(['--packages', 'components'])).toThrow( + 'Option --packages can only be used together with --add' + ) + }) + + test('parseArgs supports init command with cwd and frontend target', () => { + const options = parseArgs([ + 'init', + './web', + '--cwd', + '/tmp/module', + '--package-manager', + 'yarn', + '--no-install', + '--no-agents', + ]) + + expect(options.command).toBe('init') + if (options.command !== 'init') { + throw new Error('Expected init options') + } + + expect(options.target).toBe('./web') + expect(options.cwd).toBe('/tmp/module') + expect(options.packageManager).toBe('yarn') + expect(options.noInstall).toBe(true) + expect(options.noAgents).toBe(true) + }) + + test('parseArgs supports init dependency conflict controls', () => { + const options = parseArgs([ + 'init', + '--force-deps', + '--fix-sections', + '--no-install', + '--no-agents', + ]) + + expect(options.command).toBe('init') + if (options.command !== 'init') { + throw new Error('Expected init options') + } + + expect(options.forceDeps).toBe(true) + expect(options.fixSections).toBe(true) + }) + + test('parseArgs supports opt-in MCP client configs', () => { + const options = parseArgs([ + 'init', + '--mcp-client-configs', + 'cursor,vscode', + '--no-install', + '--no-agents', + ]) + + expect(options.command).toBe('init') + if (options.command !== 'init') { + throw new Error('Expected init options') + } + + expect(options.mcpClientConfigs).toEqual(['cursor', 'vscode']) + }) + + test('parseInitArgs rejects testing package in init mode', async () => { + const tempDir = createTempDir() + + await expect(runInit({ + ...parseInitArgs(['--cwd', tempDir, '--packages', 'testing', '--no-install', '--no-agents']), + version: '1.2.3', + })).rejects.toThrow('@retailcrm/embed-ui-v1-testing is not published for public init yet') + }) + + test('init mode creates package.json, configs and starter template without install', async () => { + const tempDir = createTempDir() + + vi.spyOn(console, 'log').mockImplementation(() => undefined) + vi.stubEnv('LANG', 'ru_RU.UTF-8') + + await runInit({ + ...parseInitArgs([ + './web', + '--cwd', + tempDir, + '--package-manager', + 'npm', + '--no-install', + '--no-agents', + '--no-mcp', + ]), + version: '1.2.3', + }) + + const packageJson = JSON.parse(fs.readFileSync(path.join(tempDir, 'package.json'), 'utf8')) + + expect(packageJson.type).toBe('module') + expect(packageJson.scripts).toMatchObject({ + build: 'vite build', + eslint: 'eslint .', + 'eslint:fix': 'eslint --fix .', + 'publish-extension': 'node scripts/publish-extension.mjs', + }) + expect(packageJson.dependencies).toMatchObject({ + '@retailcrm/embed-ui': '^1.2.3', + '@retailcrm/embed-ui-v1-components': '^1.2.3', + '@retailcrm/embed-ui-v1-contexts': '^1.2.3', + '@retailcrm/embed-ui-v1-endpoint': '^1.2.3', + '@retailcrm/embed-ui-v1-types': '^1.2.3', + '@omnicajs/vue-remote': '^0.2.23', + pinia: '^2.2', + vue: '^3.5', + 'vue-i18n': '^11', + }) + expect(packageJson.devDependencies).toMatchObject({ + '@eslint/js': '^9.39', + '@intlify/eslint-plugin-vue-i18n': '~4.3.0', + '@intlify/unplugin-vue-i18n': '^11.1', + '@omnicajs/eslint-plugin-dependencies': '^0.0.2', + '@types/node': '^22.19', + '@vitejs/plugin-vue': '^6.0', + '@vue/language-server': '^3.2', + eslint: '^9.39', + 'eslint-plugin-vue': '^10.9', + globals: '^16.5', + less: '^4.6', + typescript: '^5.9', + 'typescript-eslint': '^8.59', + vite: '^7.3', + 'vite-svg-loader': '^5.1', + 'vue-eslint-parser': '^10.4', + }) + + expect(fs.existsSync(path.join(tempDir, 'tsconfig.json'))).toBe(true) + expect(fs.readFileSync(path.join(tempDir, 'tsconfig.json'), 'utf8')).toContain('"resolveJsonModule": true') + expect(fs.readFileSync(path.join(tempDir, 'env.d.ts'), 'utf8')).toContain('declare module \'*.svg\'') + expect(fs.readFileSync(path.join(tempDir, 'eslint.config.js'), 'utf8')).toContain( + '@intlify/vue-i18n/no-dynamic-keys' + ) + expect(fs.readFileSync(path.join(tempDir, 'eslint.config.js'), 'utf8')).toContain( + 'pluginVueI18n.configs.recommended' + ) + expect(fs.readFileSync(path.join(tempDir, 'eslint.config.js'), 'utf8')).toContain( + 'order: [\'template\', \'script\', \'i18n\', \'style\']' + ) + expect(fs.readFileSync(path.join(tempDir, 'eslint.config.js'), 'utf8')).toContain( + '\'vue/html-indent\': [\'error\', 4' + ) + expect(fs.readFileSync(path.join(tempDir, 'eslint.config.js'), 'utf8')).toContain( + '\'vue/script-indent\': [\'error\', 2' + ) + expect(fs.readFileSync(path.join(tempDir, 'eslint.config.js'), 'utf8')).toContain('value-vue-components') + expect(fs.readFileSync(path.join(tempDir, 'eslint.config.js'), 'utf8')).toContain('partitions: {') + expect(fs.readFileSync(path.join(tempDir, 'vite.config.ts'), 'utf8')).toContain( + '@intlify/unplugin-vue-i18n/vite' + ) + expect(fs.readFileSync(path.join(tempDir, 'vite.config.ts'), 'utf8')).toContain( + '@omnicajs/vue-remote/vite-plugin' + ) + expect(fs.readFileSync(path.join(tempDir, 'vite.config.ts'), 'utf8')).toContain('vite-svg-loader') + expect(fs.readFileSync(path.join(tempDir, 'vite.config.ts'), 'utf8')).toContain('defaultImport: \'component\'') + expect(fs.readFileSync(path.join(tempDir, 'vite.config.ts'), 'utf8')).toContain('vueRemoteVitePlugin()') + expect(fs.readFileSync(path.join(tempDir, 'vite.config.ts'), 'utf8')).toContain('vueI18n({') + expect(fs.readFileSync(path.join(tempDir, 'vite.config.ts'), 'utf8')).toContain( + '\'@\': path.resolve(root, \'web\')' + ) + expect(fs.readFileSync(path.join(tempDir, 'web/i18n/index.ts'), 'utf8')).toContain('./locales/en-GB.json') + expect(fs.existsSync(path.join(tempDir, 'web/i18n/locales/ru-RU.json'))).toBe(true) + expect(fs.readFileSync(path.join(tempDir, 'web/endpoint/endpoint.worker.ts'), 'utf8')).toContain( + '\'order/card:common.after\': defineWidgetRunner(OrderCommonAfterWidget, setupApp)' + ) + expect(fs.readFileSync(path.join(tempDir, 'web/endpoint/endpoint.worker.ts'), 'utf8')).toContain( + 'const settings = useSettingsContext()' + ) + expect(fs.readFileSync(path.join(tempDir, 'web/endpoint/endpoint.worker.ts'), 'utf8')).toContain( + 'i18n.global.locale.value = locale.value' + ) + const settingsPage = fs.readFileSync(path.join(tempDir, 'web/pages/SettingsPage.vue'), 'utf8') + const orderWidget = fs.readFileSync(path.join(tempDir, 'web/widgets/OrderCommonAfterWidget.vue'), 'utf8') + + expect(settingsPage.indexOf('