Release/2.0.0 Обновление системы токенов

.agents/scripts/check-skills.mjs

@@ -0,0 +1,159 @@
+import assert from 'node:assert/strict'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+import process from 'node:process'
+import { pathToFileURL } from 'node:url'
+
+import { parse } from 'yaml'
+
+const read = (file) => readFileSync(file, 'utf8')
+
+const readMapping = (text) => {
+  const value = parse(text)
+  assert(
+    value && typeof value === 'object' && !Array.isArray(value),
+    'expected YAML mapping'
+  )
+
+  return value
+}
+
+const checkFrontmatter = (file, name) => {
+  const match = read(file).match(
+    /^---\r?\n(?<metadata>[\s\S]*?)\r?\n---(?:\r?\n|$)/u
+  )
+  assert(match, 'missing YAML frontmatter')
+  const metadata = readMapping(match.groups.metadata)
+  assert(
+    /^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(name) && name.length <= 64,
+    'invalid skill name'
+  )
+  assert.equal(metadata.name, name, 'name must match the skill directory')
+  assert(
+    typeof metadata.description === 'string' && metadata.description.trim(),
+    'missing description'
+  )
+}
+
+const checkManifest = (file, name) => {
+  const metadata = readMapping(read(file))
+
+  if (metadata.interface === undefined) return
+
+  const ui = metadata.interface
+  assert(
+    ui && typeof ui === 'object' && !Array.isArray(ui),
+    'invalid interface mapping'
+  )
+
+  for (const [key, value] of Object.entries(ui)) {
+    assert(
+      typeof value === 'string' && value.trim(),
+      `invalid interface.${key}`
+    )
+  }
+
+  if (ui.short_description !== undefined) {
+    assert(
+      ui.short_description.length >= 25 && ui.short_description.length <= 64,
+      'short_description must be 25–64 characters'
+    )
+  }
+
+  if (ui.default_prompt !== undefined) {
+    assert(
+      ui.default_prompt.includes(`$${name}`),
+      'default_prompt must mention its skill'
+    )
+  }
+}
+
+const checkLinks = (file, skillRoot) => {
+  const text = read(file).replace(
+    /^(?<fence>`{3,}|~{3,})[^\n]*\n[\s\S]*?^\k<fence>[ \t]*$/gmu,
+    ''
+  )
+
+  for (const {
+    groups: { target },
+  } of text.matchAll(/\[[^\]]*\]\((?<target>[^)]+)\)/gu)) {
+    const path = target.trim().replace(/^<|>$/gu, '')
+
+    if (!/^[a-z][a-z0-9+.-]*:/iu.test(path) && !path.startsWith('#')) {
+      assert(
+        existsSync(
+          resolve(dirname(file), decodeURIComponent(path.split('#')[0]))
+        ),
+        `missing link target: ${target}`
+      )
+    }
+  }
+
+  for (const {
+    groups: { target },
+  } of text.matchAll(/`(?<target>(?:references|scripts|assets)\/[^`\s]+)`/gu)) {
+    assert(existsSync(join(skillRoot, target)), `missing resource: ${target}`)
+  }
+}
+
+export const checkSkills = (repoRoot) => {
+  const errors = []
+  const check = (file, action) => {
+    try {
+      action()
+    } catch (error) {
+      errors.push(`${relative(repoRoot, file)}: ${error.message}`)
+    }
+  }
+  const skillsRoot = join(repoRoot, '.agents/skills')
+  const names = readdirSync(skillsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+    .map((entry) => entry.name)
+
+  for (const name of names) {
+    const root = join(skillsRoot, name)
+    const entry = join(root, 'SKILL.md')
+    check(entry, () => checkFrontmatter(entry, name))
+    const manifest = join(root, 'agents/openai.yaml')
+
+    if (existsSync(manifest))
+      check(manifest, () => checkManifest(manifest, name))
+
+    const references = join(root, 'references')
+    const documents = existsSync(references)
+      ? readdirSync(references, { recursive: true })
+          .filter(
+            (path) =>
+              path.endsWith('.md') && !path.split(sep).includes('vendor')
+          )
+          .map((path) => join(references, path))
+      : []
+
+    for (const file of [entry, ...documents])
+      check(file, () => checkLinks(file, root))
+  }
+
+  const agents = join(repoRoot, 'AGENTS.md')
+  check(agents, () => {
+    for (const {
+      groups: { name },
+    } of read(agents).matchAll(/\$(?<name>[a-z][a-z0-9-]*)/gu)) {
+      assert(names.includes(name), `unknown project skill: ${name}`)
+    }
+  })
+
+  return errors
+}
+
+if (import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  const errors = checkSkills(resolve(import.meta.dirname, '../..'))
+
+  if (errors.length) {
+    console.error(errors.join('\n'))
+    process.exitCode = 1
+  } else {
+    console.log(
+      'Project skill metadata, links, and AGENTS.md routing are valid.'
+    )
+  }
+}

.agents/scripts/test-check-skills.mjs

@@ -0,0 +1,88 @@
+import assert from 'node:assert/strict'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { test } from 'node:test'
+
+import { checkSkills } from './check-skills.mjs'
+
+const fixture = (context) => {
+  const root = mkdtempSync(join(tmpdir(), 'ui-kit-skills-'))
+  context.after(() => rmSync(root, { recursive: true, force: true }))
+  const write = (path, text) => {
+    const file = join(root, path)
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, text)
+  }
+  write('AGENTS.md', 'Use $sample.\n')
+  write(
+    '.agents/skills/sample/SKILL.md',
+    '---\nname: sample\ndescription: Example skill\n---\n[Guide](references/guide.md)\n'
+  )
+  write('.agents/skills/sample/references/guide.md', '# Guide\n')
+  write(
+    '.agents/skills/sample/agents/openai.yaml',
+    'interface:\n  short_description: "Describe a valid example skill"\n  default_prompt: "Use $sample for this task."\n'
+  )
+
+  return { root, write }
+}
+
+test('accepts valid metadata, linked references, and project routing', (context) => {
+  const { root, write } = fixture(context)
+  write('.agents/skills/sample/vendor/copied/SKILL.md', 'not active metadata')
+  assert.deepEqual(checkSkills(root), [])
+})
+
+test('reports malformed YAML in entrypoints and manifests', (context) => {
+  const { root, write } = fixture(context)
+  write(
+    '.agents/skills/sample/SKILL.md',
+    '---\nname: sample\nname: duplicate\n---\n'
+  )
+  write('.agents/skills/sample/agents/openai.yaml', 'interface: [\n')
+  const errors = checkSkills(root)
+  assert.equal(errors.length, 2)
+  assert(
+    errors.some((error) => error.startsWith('.agents/skills/sample/SKILL.md:'))
+  )
+  assert(
+    errors.some((error) =>
+      error.startsWith('.agents/skills/sample/agents/openai.yaml:')
+    )
+  )
+})
+
+test('reports missing links and literal resources while ignoring examples and remote URLs', (context) => {
+  const { root, write } = fixture(context)
+  write(
+    '.agents/skills/sample/references/guide.md',
+    '[Remote](https://example.com)\n[Section](#section)\n```md\n[Example](placeholder.md)\n```\n[Missing](missing.md)\n'
+  )
+  let errors = checkSkills(root)
+  assert.equal(errors.length, 1)
+  assert.match(errors[0], /missing\.md/u)
+  write(
+    '.agents/skills/sample/references/guide.md',
+    'Run `scripts/missing.mjs`.\n'
+  )
+  errors = checkSkills(root)
+  assert.equal(errors.length, 1)
+  assert.match(errors[0], /scripts\/missing\.mjs/u)
+})
+
+test('reports a mismatched skill name, invalid prompt, and unresolved AGENTS routing', (context) => {
+  const { root, write } = fixture(context)
+  write(
+    '.agents/skills/sample/SKILL.md',
+    '---\nname: another\ndescription: Example skill\n---\n'
+  )
+  write(
+    '.agents/skills/sample/agents/openai.yaml',
+    'interface:\n  default_prompt: "Use $another."\n'
+  )
+  write('AGENTS.md', 'Use $missing.\n')
+  const errors = checkSkills(root)
+  assert.equal(errors.length, 3)
+  assert(errors.some((error) => error.startsWith('AGENTS.md:')))
+})

.agents/skills/ui-kit-component-docs/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: ui-kit-component-docs
+description: >
+  Write or shorten Russian UI Kit component Markdown and public API JSDoc,
+  excluding task descriptions, migration reports, and release notes.
+---
+
+# Документация компонентов Prime UI Kit
+
+Сверь публичные props, экспорты, defaults, примеры и поведение с исходниками,
+тестами и Storybook. За образец бери актуальные Tag, Badge, Button или Input.
+Пример другой ветки читай через `git show`, не переключая рабочую область.
+
+## Markdown
+
+Создавай `<Component>.md` рядом с компонентом. Используй только нужные разделы:
+
+1. Название и одно предложение о назначении.
+2. `Использование` — минимальный пример с публичным импортом пакета.
+3. `Props` — сначала назначение собственного prop, затем существенные варианты,
+   defaults (включая встроенные иконки) и ограничения сочетаний. Добавь
+   относительную ссылку на публичный тип, для вложенного компонента — на его
+   тип.
+4. `Доступность` — как получается доступное имя, роли и ответственность
+   потребителя. Если разработчику нужно задать имя или учесть другой нюанс,
+   добавь короткую рекомендацию с условием её применения. При необходимости
+   поясни интерактивного родителя и масштаб шрифта.
+5. `Макет` — точная известная ссылка на компонент в Figma.
+
+Стандартные RN props не перечисляй, особое поведение объясняй по месту. Сначала
+опиши назначение prop, затем особенности a11y. `accessibilityLabel` описывай в
+доступности: различай автоматическое озвучивание компонента и добавление его
+смысла потребителем в доступное имя родителя.
+
+## JSDoc И Краткость
+
+Для изменяемого публичного компонента и его собственных props опиши назначение,
+смысл callback, controlled-поведение, defaults и существенные ограничения.
+Рекомендацию для потребителя повтори в JSDoc соответствующего prop или
+компонента, чтобы она была видна при использовании API в редакторе. Добавляй
+точную известную Figma-ссылку через `@see`. Для deprecated API укажи замену без
+неподтверждённого срока удаления.
+
+Пиши кратко по-русски, без повторов, внутренних функций, токенов, тестов и
+хронологии. Сохраняй подтверждённые ограничения: сокращение текста, условия
+label/caption, обязательную иконку и доступное имя для iconOnly. Не обещай
+непроверенные платформенные возможности.
+
+Совместимость и миграцию не включай в документацию компонента. Если запрошены,
+выдай отдельно в чате. README и ссылки из Storybook меняй только по запросу,
+сохраняя существующий формат.
+
+## Проверка
+
+Проверь относительные ссылки и точный Figma-узел. Запусти целевой Prettier и
+`git diff --check`; остальные проверки и отчёт — по `AGENTS.md`.

.agents/skills/ui-kit-component-docs/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: 'UI Kit Component Docs'
+  short_description: 'Write Russian component Markdown and API JSDoc'

.agents/skills/ui-kit-figma/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: ui-kit-figma
+description: >
+  Inspect Figma components, sync UI Kit implementations and theme-token
+  bindings, or update exact design links. Read-only toward Figma.
+---
+
+# UI Kit Figma
+
+Use the node and file/branch identity from the supplied link; do not substitute
+the current selection. Use the Figma design-to-code skill before design-context
+calls. Implementation uses existing tokens; token changes or regeneration
+require confirmation under `AGENTS.md`.
+
+## Inspect A Design
+
+For identification, description, or a screenshot, inspect the explicit node and
+use structural metadata as needed. Return the actual image when a screenshot is
+requested. Distinguish visible facts, metadata-backed properties, and behavioral
+inference; a static frame does not prove interaction behavior. Skip token
+mapping, implementation, tests, and story edits for inspection-only requests.
+Report unavailable evidence without inventing results.
+
+## Component Synchronization
+
+1. Inspect the component source, public types and barrels, nearest tests and
+   stories, and relevant files under `src/theme/tokens`.
+2. Read [token-mapping.md](references/token-mapping.md). Call Figma design
+   context on the exact component or variant frame. If a page or section returns
+   sparse context, use metadata only to locate the inner frame, then call design
+   context on that frame.
+3. Read variable definitions for the target frame and map each relevant Figma
+   variable to the existing runtime theme path.
+4. Implement the smallest compatible source change, following the nearest
+   component pattern and root `AGENTS.md`. Use `ui-kit-public-api` when the
+   public contract changes.
+5. Use `ui-kit-testing` for changed behavior and `ui-kit-storybook` for affected
+   public scenarios, controls, and device verification. Compare rendered states
+   with the exact frame when visual alignment is in scope. Do not use static
+   style assertions to prove a Figma mapping.
+6. Update the component documentation link when its exact Figma frame is known.
+7. Run the verification required by root `AGENTS.md`.
+
+## Links Only
+
+- Link a component to its exact Figma component or variant frame, not merely the
+  file, page, or broad section containing it.
+- In a bulk link update, inventory the component documentation first. Update
+  only confidently matched frames and keep unresolved components explicit.
+- Use supplied exact links directly; inspect Figma metadata to resolve missing
+  frames. Fetch design context only if metadata cannot establish the match.
+- Skip token mapping, implementation, tests, and story changes unless requested.
+  Validate links and document formatting; report updated and unresolved links
+  separately, including before a requested commit.

.agents/skills/ui-kit-figma/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: 'UI Kit Figma'
+  short_description: 'Inspect Figma designs and sync UI Kit components'
+  default_prompt:
+    'Use $ui-kit-figma to inspect a design or sync a UI Kit component from its
+    Figma specification.'

.agents/skills/ui-kit-figma/references/token-mapping.md

@@ -0,0 +1,18 @@
+# Token Mapping
+
+- Treat Figma variable bindings as the source of token intent. Resolved pixels
+  and colors are inspection data, not values to copy into source.
+- Use `design-tokens/input/tokens.json` as the latest designer export and
+  `src/theme/tokens/**` as generated output. Follow `AGENTS.md` for explicit
+  confirmation before changing token values or regenerating output; ordinary
+  synchronization does not grant that approval.
+- Reuse existing runtime theme paths; do not hardcode resolved values when a
+  matching local token exists.
+- Prefer a component token when Figma explicitly binds that property to a
+  component variable. Use a semantic token when the intent is semantic or no
+  component binding exists.
+- If an exact value has no matching token, report the gap and the part that
+  cannot be matched with current tokens. Do not hardcode it, silently substitute
+  an approximate token, or change token data without the required confirmation.
+- Apply severity, size, state, and theme bindings to every affected layer: text,
+  background, border, icon, and shape, not only the outer container.