@retailcrm/embed-ui-v1-contexts 0.9.24 → 0.9.26

package/README.md

@@ -60,6 +60,16 @@ npx @retailcrm/embed-ui-v1-contexts init-agents
 такого блока там ещё нет. С `--force` можно обновить уже существующий блок
 пакета.
 
+Для project-level skills можно создать `.agents/skills/embed-ui-v1-contexts-usage/SKILL.md`:
+
+```bash
+npx @retailcrm/embed-ui-v1-contexts init-skills
+```
+
+Skill описывает повторяемый workflow применения контекстов в коде: проверку доступности
+контекста в target, выбор public import, readonly/writable семантику, actions и fallback
+на generated YAML profiles, если MCP недоступен.
+
 ## Инициализация MCP-конфига
 
 Пакет также может сам добавить project-level MCP-настройки в целевой проект:

package/bin/embed-ui-v1-contexts.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { fileURLToPath } from 'node:url'
 import fs from 'node:fs'
 import path from 'node:path'
 import process from 'node:process'
@@ -12,6 +13,8 @@ const AGENTS_SECTION_END = '<!-- embed-ui-agents:@retailcrm/embed-ui-v1-contexts
 const README_MCP_SECTION_HEADER = '## MCP For AI Assistants: @retailcrm/embed-ui-v1-contexts'
 const README_MCP_MARKER = 'embed-ui-v1-contexts://contexts'
 const MCP_SERVER_NAME = 'retailcrm-embed-ui-v1-contexts'
+const SKILL_NAME = 'embed-ui-v1-contexts-usage'
+const SKILL_TEMPLATE_PATH = `templates/skills/${SKILL_NAME}/SKILL.md.txt`
 const MCP_BIN_NAME = process.platform === 'win32' ? 'embed-ui-v1-contexts-mcp.cmd' : 'embed-ui-v1-contexts-mcp'
 const RELATIVE_MCP_BIN_PATH = `./node_modules/.bin/${MCP_BIN_NAME}`
 const CLAUDE_PROJECT_MCP_BIN_PATH = `\${CLAUDE_PROJECT_DIR:-.}/node_modules/.bin/${MCP_BIN_NAME}`
@@ -48,6 +51,7 @@ const MCP_CLIENT_CONFIGS = {
 const HELP_TEXT = `Usage:
   npx ${PACKAGE_NAME} init-agents [target] [options]
   npx ${PACKAGE_NAME} init-config [target] [options]
+  npx ${PACKAGE_NAME} init-skills [target] [options]
 
 Options:
   -f, --force                  Replace existing managed sections and MCP server entries
@@ -57,6 +61,7 @@ Options:
 
 Examples:
   npx ${PACKAGE_NAME} init-agents
+  npx ${PACKAGE_NAME} init-skills
   npx ${PACKAGE_NAME} init-agents ./my-project
   npx ${PACKAGE_NAME} init-agents --force
   npx ${PACKAGE_NAME} init-config ./my-project
@@ -74,6 +79,10 @@ const printMcpNotice = (message) => {
   console.log(`MCP: ${message}`)
 }
 
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+const createSkill = () => fs.readFileSync(path.join(packageRoot, SKILL_TEMPLATE_PATH), 'utf8')
+
 const parseArgs = (argv) => {
   const options = {
     command: null,
@@ -459,6 +468,35 @@ const initAgents = (target, force) => {
   console.log(`The ${PACKAGE_NAME} instructions were appended to the end of the file.`)
 }
 
+const initSkills = (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 skillPath = path.join(target, '.agents', 'skills', SKILL_NAME, 'SKILL.md')
+  const fileExists = fs.existsSync(skillPath)
+
+  if (fileExists && !options.force) {
+    console.log(`${skillPath} already exists`)
+    console.log('Nothing was changed. Re-run with --force to refresh that skill.')
+    return
+  }
+
+  if (!options.dryRun) {
+    fs.mkdirSync(path.dirname(skillPath), { recursive: true })
+    fs.writeFileSync(skillPath, createSkill(), 'utf8')
+  }
+
+  const action = fileExists ? 'updated' : 'created'
+  console.log(`SKILL: ${options.dryRun ? `would ${action}` : action} ${skillPath}`)
+}
+
 const writeMcpServerConfig = (target, relativePath, rootField, options, serverConfig) => {
   const filePath = path.join(target, relativePath)
   const fileExists = fs.existsSync(filePath)
@@ -575,6 +613,11 @@ const main = () => {
       return
     }
 
+    if (options.command === 'init-skills') {
+      initSkills(options.target, options)
+      return
+    }
+
     throw new Error(`Unknown command: ${options.command}`)
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error))

package/package.json

@@ -6,7 +6,7 @@
   },
   "description": "Reactive contexts for RetailCRM JS API",
   "type": "module",
-  "version": "0.9.24",
+  "version": "0.9.26",
   "license": "MIT",
   "author": "RetailDriverLLC <integration@retailcrm.ru>",
   "repository": {
@@ -104,7 +104,8 @@
     "dist",
     "docs",
     "types",
-    "README.md"
+    "README.md",
+    "templates"
   ],
   "scripts": {
     "build": "yarn prepare && yarn build:docs && yarn build:code && yarn build:mcp && yarn build:meta",
@@ -123,11 +124,11 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@omnicajs/symfony-router": "^1.0.0",
-    "@retailcrm/embed-ui-v1-types": "^0.9.24"
+    "@retailcrm/embed-ui-v1-types": "^0.9.26"
   },
   "devDependencies": {
     "@remote-ui/rpc": "^1.4.7",
-    "@retailcrm/embed-ui-v1-testing": "^0.9.24",
+    "@retailcrm/embed-ui-v1-testing": "^0.9.26",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vite": "^7.3.2",

package/templates/skills/embed-ui-v1-contexts-usage/SKILL.md.txt

@@ -0,0 +1,46 @@
+---
+name: embed-ui-v1-contexts-usage
+description: Use when applying RetailCRM JS API contexts in extension code with @retailcrm/embed-ui-v1-contexts. Covers target-to-context selection, public imports, readonly versus writable fields, actions, custom contexts, dictionaries, and MCP/profile fallback.
+---
+
+# Embed UI v1 Contexts Usage
+
+Use this skill before changing code that reads CRM page data, writes context fields, calls context actions, or works with custom fields through `@retailcrm/embed-ui-v1-contexts`.
+
+## Reading order
+
+1. Read project `AGENTS.md` if it exists.
+2. Read `./node_modules/@retailcrm/embed-ui-v1-contexts/README.md`.
+3. Read `./node_modules/@retailcrm/embed-ui-v1-contexts/docs/ru/CONCEPT.md`.
+4. Read `./node_modules/@retailcrm/embed-ui-v1-contexts/docs/ru/CUSTOM.md` if custom fields or custom dictionaries are involved.
+5. If the task is tied to a widget target and endpoint MCP is available, read that target profile first; it is the source of truth for available `contexts`, `custom_contexts`, and `action_scopes`.
+6. If contexts MCP resources are available, start from:
+   - `embed-ui-v1-contexts://contexts`
+   - `embed-ui-v1-contexts://actions`
+   - `embed-ui-v1-contexts://custom-contexts`
+7. Then read the specific profile before coding:
+   - `embed-ui-v1-contexts://contexts/<encoded-context>`
+   - `embed-ui-v1-contexts://actions/<encoded-scope>`
+   - `embed-ui-v1-contexts://custom-contexts/<encoded-entity>`
+8. If MCP is not available, use generated YAML profiles from `./node_modules/@retailcrm/embed-ui-v1-contexts/docs/contexts/*.yml`, `docs/actions/*.yml`, and `docs/custom-contexts/*.yml`.
+
+## Workflow
+
+1. Identify where the code runs: CRM page, widget target, page runner, or shared remote module.
+2. Confirm that the needed context, custom context, or action scope is available there; do not infer availability from page names or target ids.
+3. Pick the exact public entrypoint from the profile `public_import` or docs, such as `@retailcrm/embed-ui-v1-contexts/remote/order/card`.
+4. Read context fields through `useContext()` and keep UI state derived from reactive store values instead of copying context data into parallel state.
+5. For writes, check the field `readonly` flag and `mutation` notes. Assign only writable fields directly.
+6. For readonly aggregates or business operations, use the documented `useActions()` method and payload shape instead of mutating nested data.
+7. For custom contexts, call `initialize()` before relying on schema-backed fields, handle rejection, and use `useCustomField()` with the expected `kind`.
+8. For custom dictionary fields, resolve the dictionary code from the schema and load options through `useDictionary()`.
+
+## High-signal checks
+
+- Do not assume all contexts are available on all targets.
+- Do not import from `@retailcrm/embed-ui-v1-contexts/dist/*`, source files, or repository-only paths.
+- Do not infer mutability from TypeScript shape alone; read the generated profile action and mutation notes.
+- Use current item identifiers from the context, such as `OrderItem.index`, when action notes require them.
+- Preserve host-mediated behavior: let CRM perform action validation, mutation, and synchronization.
+- If a field description is vague or absent, state that any business meaning is an inference.
+- Keep context usage aligned with endpoint target profiles when `@retailcrm/embed-ui-v1-endpoint` is also installed.