@uzum-tech/design-tokens-resolver 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,642 @@
-# Temporary Holding Version
+<p align="center">
+  <img width="144px" src="https://ik.imagekit.io/jbalancer/uzum-logo.svg?updatedAt=1692012347116" />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @uzum-tech/design-tokens-resolver
+
+> Забирает опубликованные дизайн-токены из сервиса дизайн-токенов — по номеру версии
+> или по каналу раскатки, — сверяет целостность и кладёт на диск.
+> Команда токенов двигает канал, продуктовые проекты ничего не
+> подтверждают руками.
+
+---
+
+## Содержание
+
+- [Зачем](#зачем)
+- [Установка](#установка)
+- [Быстрый старт](#быстрый-старт)
+- [Конфигурация](#конфигурация)
+  - [Стенды](#стенды)
+  - [Объект или async-геттер](#объект-или-async-геттер)
+  - [Доступ: ключ или Basic](#доступ-ключ-или-basic)
+  - [Все поля конфига](#все-поля-конфига)
+- [Командная строка](#командная-строка)
+- [Версия или канал](#версия-или-канал)
+- [Форма выгрузки](#форма-выгрузки)
+- [API инстанса](#api-инстанса)
+- [Как работает проверка целостности](#как-работает-проверка-целостности)
+- [Повторы при сбоях](#повторы-при-сбоях)
+- [Лок-файл](#лок-файл)
+- [Ошибки](#ошибки)
+- [Рецепты](#рецепты)
+- [FAQ](#faq)
+
+---
+
+## Зачем
+
+Дизайн-токены живут в Figma, а нужны в коде — и в вебе, и на мобилках.
+Между ними стоит движок: он хранит неизменяемые релизы и
+указатели-каналы (`latest`, `next`). Резолвер — единственное, что нужно
+продуктовой команде, чтобы получить нужную версию в свой репозиторий.
+
+Что внутри:
+
+- **выбор версии** — по номеру или по каналу раскатки, на который сейчас
+  указывает команда дизайн-системы;
+- **проверка целостности** — `sha256` канонического тела сверяется с
+  `contentHash` релиза до того, как что-то попадёт на диск;
+- **стенды** — потребитель называет `local`, `development` или
+  `production`, адреса знает пакет;
+- **нарезки** — одна коллекция, форма `flat` или `dtcg`, разворачивание
+  алиасов до литеральных значений;
+- **лок-файл** — паспорт сборки: версия, хеш, адрес движка, кто и когда
+  опубликовал;
+- **повторы** — временные отказы сети не роняют пайплайн.
+
+Публикация токенов и их выкатка в продукт разведены намеренно. Резолвер
+ничего не публикует и не двигает — только читает.
+
+---
+
+## Установка
+
+```bash
+pnpm add -D @uzum-tech/design-tokens-resolver
+```
+
+Требуется **Node.js >= 20.18.1**. Зависимостей у пакета нет.
+
+Разово, без установки:
+
+```bash
+npx @uzum-tech/design-tokens-resolver --env development --channel latest
+```
+
+Пакет собран в двух форматах, поэтому работает и в CommonJS-проектах,
+и в ESM:
+
+```ts
+// ESM
+import DesignTokensResolver from '@uzum-tech/design-tokens-resolver';
+
+// CommonJS
+const DesignTokensResolver = require('@uzum-tech/design-tokens-resolver').default;
+```
+
+---
+
+## Быстрый старт
+
+Кладём в корень проекта `design-tokens.config.mjs`:
+
+```js
+export default () => ({
+  env: process.env.DESIGN_TOKENS_ENV ?? 'production',
+  apiKey: process.env.DESIGN_TOKENS_API_KEY,
+
+  outputPath: './src/tokens',
+  collection: 'base-b2b',
+  channel: 'latest'
+});
+```
+
+Добавляем скрипт и зовём его перед сборкой:
+
+```json
+{
+  "scripts": {
+    "tokens": "design-tokens-resolver --resolve",
+    "prebuild": "pnpm tokens"
+  }
+}
+```
+
+```
+$ pnpm tokens
+Движок https://tokens.example.com/api/v1
+Версия 1.0.0, хеш d56a34ce7331061c1ea3433b6ed5a7669727797b6b9d98dea950229df989db38
+Токены: src/tokens/tokens.json (12958 байт)
+Лок: src/tokens/tokens.lock.json
+```
+
+Адрес движка печатается первой строкой, до любых запросов — по логу
+сборки всегда видно, откуда приехали токены.
+
+Оба файла стоит коммитить: `tokens.json` — то, что попадёт в сборку,
+`tokens.lock.json` — чем это подтверждается.
+
+---
+
+## Конфигурация
+
+Резолвер ищет конфиг вверх по дереву от текущего каталога. Порядок
+поиска:
+
+```
+design-tokens.config.mjs
+design-tokens.config.js
+design-tokens.config.cjs
+design-tokens.config.json
+```
+
+Исполняемый конфиг предпочтительнее: в нём доступны переменные
+окружения, поэтому ключи не приходится дублировать в настройках
+пайплайна.
+
+### Стенды
+
+Адресов движка в конфиге проекта нет: потребитель называет стенд, адреса
+знает пакет.
+
+| Стенд | Назначение |
+|---|---|
+| `local` | локальный стенд разработчика |
+| `development` | тестовый стенд |
+| `production` | боевой стенд |
+
+По умолчанию `production` — продуктовому проекту не нужно задавать
+ничего. Инфраструктура переезжает — чинится в одном месте, в пакете, а не
+в конфиге каждого репозитория.
+
+Опечатка в имени ловится до обращения к сети:
+
+```
+$ design-tokens-resolver --env stage
+CONFIG_INVALID: Unknown environment "stage". Known: local, development, production
+```
+
+Если движок поднят не по адресу стенда — например, локально на другом
+порту, — есть `baseUrl`. Он перекрывает выбор целиком.
+
+### Объект или async-геттер
+
+Экспортом может быть и сам объект, и функция — синхронная либо
+асинхронная:
+
+```js
+// объект
+export default {
+  env: 'production',
+  channel: 'latest'
+};
+
+// async-геттер: ключ можно достать из хранилища секретов
+export default async () => ({
+  env: 'production',
+  apiKey: await readSecret('design-tokens-api-key'),
+  channel: 'latest'
+});
+```
+
+Возвращать нужно объект по умолчанию (`export default`) — без него
+резолвер бросит `CONFIG_INVALID`.
+
+### Доступ: ключ или Basic
+
+Поддерживаются оба способа, ключ имеет приоритет:
+
+| Способ | Откуда берётся |
+|---|---|
+| API-ключ | `--api-key`, `DESIGN_TOKENS_API_KEY`, либо `apiKey` в конфиге |
+| Basic | `--username`/`--password`, `DESIGN_TOKENS_USERNAME`/`DESIGN_TOKENS_PASSWORD`, либо `auth` в конфиге |
+
+Ключ уходит заголовком `x-api-key`, Basic — заголовком `authorization`.
+Если не задано ничего, резолвер ходит без заголовков — движок при этом
+ответит `401`, если выгрузка релизов на нём закрыта. Сам резолвер доступ
+не требует: ключ заводится и хранится на стороне потребителя.
+
+На `401` в подсказке к ошибке перечисляется, что именно нужно задать.
+
+### Все поля конфига
+
+Все поля опциональны:
+
+| Поле | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `env` | `ConfigTypes.Env` | `'production'` | Стенд: `local`, `development`, `production` |
+| `baseUrl` | `string` | — | Адрес движка в обход стендов |
+| `apiKey` | `string` | — | Уходит заголовком `x-api-key` |
+| `auth` | `ConfigTypes.Auth` | — | `{ username, password }` для Basic |
+| `channel` | `string` | — | Канал раскатки: `latest` или `next` |
+| `collection` | `string` | — | Отдать только одну коллекцию |
+| `outputPath` | `string` | `process.cwd()` | Каталог для файлов |
+| `fileName` | `string` | `'tokens.json'` | Имя файла с токенами |
+| `requestTimeoutInMs` | `number` | `30000` | Таймаут одного запроса |
+| `retryCount` | `number` | `2` | Сколько раз повторить временный отказ |
+| `retryDelayInMs` | `number` | `500` | Базовая пауза между попытками |
+
+Версия в конфиг намеренно не кладётся: `--version` — разовый флаг для
+хотфикса или расследования. Иначе проект тихо отстанет от канала.
+
+---
+
+## Командная строка
+
+| Флаг | Что делает |
+|---|---|
+| `--env <стенд>` | `local`, `development` или `production`; либо `DESIGN_TOKENS_ENV` |
+| `--base-url <url>` | адрес движка в обход стендов; либо `DESIGN_TOKENS_BASE_URL` |
+| `--version <semver>` | конкретная версия релиза |
+| `--channel <slug>` | взять версию, на которую сейчас указывает канал |
+| `--collection <slug>` | только одна коллекция |
+| `--format <flat\|dtcg>` | форма выгрузки, по умолчанию `flat` |
+| `--resolve` | развернуть алиасы до литеральных значений |
+| `--output-path <путь>` | куда сохранить |
+| `--file-name <имя>` | имя файла, по умолчанию `tokens.json` |
+| `--no-lock` | не писать `tokens.lock.json` |
+| `--api-key <ключ>` | либо `DESIGN_TOKENS_API_KEY` |
+| `--username <логин>` | либо `DESIGN_TOKENS_USERNAME` |
+| `--password <пароль>` | либо `DESIGN_TOKENS_PASSWORD` |
+
+Приоритет источников: **флаг → переменная окружения → конфиг проекта →
+умолчание**.
+
+---
+
+## Версия или канал
+
+Версию можно задать двумя способами, и они взаимоисключающие по смыслу:
+
+```bash
+design-tokens-resolver --channel latest   # то, на что сейчас указывает канал
+design-tokens-resolver --version 1.0.0    # конкретный релиз
+```
+
+Если заданы оба, побеждает `--version`. Если не задан ни один —
+`CONFIG_INVALID`, до обращения к сети.
+
+Каналов два: `latest` — стабильный, `next` — обкатать релиз до того, как
+он станет стабильным. Канал может существовать, но ещё ни на что не
+указывать — тогда `CHANNEL_EMPTY`.
+
+Продуктовому проекту нужен канал, а не версия: тогда выкатка новых
+токенов — решение команды дизайн-системы, а не задача каждого
+репозитория.
+
+---
+
+## Форма выгрузки
+
+`flat` — всегда документ одной и той же формы, независимо от
+`--collection` и `--resolve`:
+
+```json
+{
+  "schemaVersion": 1,
+  "collections": [
+    { "slug": "base-b2b", "layout": "SINGLE_MODE", "modes": [ { "slug": "default", "isDefault": true } ] }
+  ],
+  "tokens": [
+    { "collection": "base-b2b", "mode": "default", "path": "color.blue.100", "$type": "color", "$value": "#eef2fc" },
+    { "collection": "product", "mode": "b2b-dark", "path": "accent.brand", "$type": "color", "$value": "{base-b2b.color.violet.500}" }
+  ]
+}
+```
+
+`--collection` сужает и `tokens`, и `collections`; `--resolve` заменяет
+ссылки вида `{коллекция.путь}` на литеральные значения. Ключи верхнего
+уровня при этом не меняются, поэтому кодогенератор проекта можно писать
+один раз и не переучивать под набор флагов.
+
+`dtcg` — другая форма по определению: дерево групп. С `--collection` это
+дерево одной коллекции, без него — дерево деревьев, по одному на
+коллекцию.
+
+Кодогенерации почти всегда нужен `--resolve`: без него алиасы приходят
+ссылками, и разворачивать их придётся самому.
+
+---
+
+## API инстанса
+
+```ts
+import DesignTokensResolver, { ConfigTypes } from '@uzum-tech/design-tokens-resolver';
+
+const resolver = new DesignTokensResolver({
+  env: ConfigTypes.Env.PRODUCTION,
+  apiKey: process.env.DESIGN_TOKENS_API_KEY
+});
+```
+
+Конструктор резолвит конфиг сразу, поэтому неверный стенд или неполный
+логин-пароль бросят `CONFIG_INVALID` на месте, а не на первом запросе.
+
+#### `resolve(request): Promise<ResolveTypes.Result>`
+
+Главный метод: выбирает версию, проверяет целостность, пишет токены и
+лок на диск.
+
+```ts
+const result = await resolver.resolve({
+  channel: 'latest',
+  collection: 'base-b2b',
+  resolve: true,
+  outputPath: './src/tokens'
+});
+
+result.release.version;   // '1.0.0'
+result.tokensPath;        // 'src/tokens/tokens.json'
+result.lockPath;          // 'src/tokens/tokens.lock.json' либо null
+result.bytesWritten;      // 12958
+result.source.baseUrl;    // 'https://tokens.example.com/api/v1'
+```
+
+Пути возвращаются в том же виде, в каком задан `outputPath`: относительный
+путь остаётся относительным. Каталог создаётся, если его нет.
+
+`lock: false` отключает запись лока — тогда `lockPath` будет `null`.
+
+#### `fetchVerified(target): Promise<ResolveTypes.Verified>`
+
+То же самое, но без записи на диск: отдаёт проверенное тело и метаданные
+релиза. Удобно, если нужно собрать что-то своё.
+
+```ts
+const { release, body } = await resolver.fetchVerified({
+  version: '1.0.0',
+  format: ConfigTypes.Format.DTCG,
+  collection: 'base-b2b'
+});
+```
+
+#### `resolveVersion(target): Promise<string>`
+
+Превращает канал в номер версии. Если версия уже задана — возвращает её
+как есть, без сетевых запросов.
+
+```ts
+const version = await resolver.resolveVersion({ channel: 'latest' });
+// '1.0.0'
+```
+
+Бросает `CHANNEL_EMPTY`, если канал существует, но ещё ни на что не
+указывает, и `RELEASE_NOT_FOUND`, если такого канала нет.
+
+#### `getSource(): ResolveTypes.Source`
+
+Адрес движка, с которым работает экземпляр. Сетевых запросов не делает —
+это то, что CLI печатает первой строкой.
+
+---
+
+## Как работает проверка целостности
+
+Перед записью резолвер всегда запрашивает **каноническое**
+представление релиза — без фильтров, `format=flat`, без резолва — и
+сверяет его `sha256` с `contentHash` из метаданных релиза. Не сошлось —
+`INTEGRITY_MISMATCH`, и на диск не пишется ничего.
+
+Порядок такой:
+
+1. канал → версия, если версия не задана явно;
+2. метаданные релиза, включая `contentHash`;
+3. каноническое тело и сверка хеша;
+4. нарезка отдельным запросом, если заданы `--collection`, `--resolve`
+   или `--format dtcg`.
+
+Четвёртый шаг — цена за третий: хеш считается от канонической формы, а
+любая нарезка меняет байты. Один лишний GET за то, что подменённые в базе
+байты не доедут до сборки незамеченными.
+
+Хеш зависит от содержимого, а не от номера версии. Это важно, потому что
+dev и prod — независимые движки со своими таблицами релизов, и версия
+`1.0.0` на них может содержать разное.
+
+---
+
+## Повторы при сбоях
+
+Сетевой сбой и «пятисотка» — не повод ронять сборку, поэтому запросы
+повторяются: три попытки, паузы 500 мс и 1 секунда.
+
+| Ответ | Поведение |
+|---|---|
+| обрыв связи, таймаут | повтор |
+| `429`, любой `5xx` | повтор |
+| `401`, `403` | сразу ошибка — доступ сам не починится |
+| `404` | сразу ошибка — версии или канала нет |
+
+Отдельный запрос не может висеть дольше таймаута — по умолчанию 30
+секунд:
+
+```js
+export default () => ({
+  env: 'production',
+  requestTimeoutInMs: 30000,
+  retryCount: 2,
+  retryDelayInMs: 500
+});
+```
+
+`retryCount: 0` выключает повторы совсем. В худшем случае команда займёт
+`(retryCount + 1) × requestTimeoutInMs` плюс паузы — это стоит держать в
+голове, выставляя таймаут джобы в пайплайне.
+
+---
+
+## Лок-файл
+
+Рядом с токенами пишется `tokens.lock.json`:
+
+```json
+{
+  "version": "1.0.0",
+  "contentHash": "d56a34ce7331061c1ea3433b6ed5a7669727797b6b9d98dea950229df989db38",
+  "baseUrl": "https://tokens.example.com/api/v1",
+  "byteSize": 222111,
+  "publishedAt": "2026-09-04T08:15:31.237Z",
+  "publishedBy": "designer",
+  "sourceLabel": "figma-2026-08"
+}
+```
+
+Времени скачивания в нём нет — только свойства релиза. Поэтому повторный
+запуск на той же версии даёт побайтово тот же файл, а дифф в merge
+request показывает смену версии, а не шум.
+
+Лок отвечает на вопрос «откуда это приехало» месяц спустя: какая версия,
+с какого движка, кто и когда её опубликовал. В CI его стоит класть в
+артефакты рядом с бандлом.
+
+---
+
+## Ошибки
+
+Все ошибки пакета — экземпляры `ResolverError` с полем `code`:
+
+```ts
+import { ErrorTypes, ResolverError } from '@uzum-tech/design-tokens-resolver';
+
+try {
+  await resolver.resolve({ channel: 'latest', outputPath: './src/tokens' });
+} catch (error) {
+  if (ResolverError.is(error, ErrorTypes.Code.REQUEST_FAILED)) {
+    error.statusCode; // 401
+    error.body;       // тело ответа движка
+  }
+}
+```
+
+| Код | Когда возникает |
+|---|---|
+| `CONFIG_INVALID` | Неизвестный стенд, неполный логин-пароль, не заданы ни версия ни канал, конфиг без `export default` |
+| `REQUEST_FAILED` | Движок недоступен или ответил статусом >= 400 |
+| `RELEASE_NOT_FOUND` | Нет такой версии или такого канала |
+| `CHANNEL_EMPTY` | Канал есть, но пока ни на что не указывает |
+| `INTEGRITY_MISMATCH` | `sha256` тела не совпал с `contentHash` релиза |
+| `WRITE_FAILED` | Не удалось записать файл |
+
+`ResolverError.is(error)` без второго аргумента проверяет только тип.
+Оба варианта сужают тип для TypeScript, так что после проверки
+`error.statusCode` доступен без приведения.
+
+В CLI ошибка печатается как `КОД: сообщение`, процесс завершается с
+кодом `1`. На `401` добавляется подсказка, какие переменные окружения
+нужно задать.
+
+---
+
+## Рецепты
+
+### Вебовый проект
+
+```json
+{
+  "scripts": {
+    "tokens": "design-tokens-resolver --resolve",
+    "tokens:css": "node scripts/tokens-to-css.mjs",
+    "predev": "pnpm tokens && pnpm tokens:css",
+    "prebuild": "pnpm tokens && pnpm tokens:css"
+  }
+}
+```
+
+Разовые сценарии поверх тех же скриптов:
+
+```bash
+pnpm tokens --version 1.4.0        # хотфикс на конкретной версии
+pnpm tokens --channel next         # посмотреть, что идёт следующим
+DESIGN_TOKENS_ENV=development pnpm tokens
+```
+
+### GitLab CI
+
+```yaml
+tokens:
+  variables:
+    DESIGN_TOKENS_ENV: production
+  script:
+    - pnpm i --frozen-lockfile
+    - pnpm tokens
+    - git diff --exit-code ./src/tokens || echo "токены обновились"
+  artifacts:
+    paths:
+      - src/tokens/tokens.lock.json
+```
+
+Ключ — в переменных CI, masked и protected. Стенд задаётся одной
+переменной, адрес подставляет пакет.
+
+### Две коллекции в одном проекте
+
+Лок всегда называется `tokens.lock.json`, поэтому двум коллекциям нужны
+разные каталоги:
+
+```bash
+design-tokens-resolver --collection base-b2b --output-path ./src/tokens/base
+design-tokens-resolver --collection product --output-path ./src/tokens/product
+```
+
+### Свой кодогенератор поверх тела
+
+```ts
+import DesignTokensResolver from '@uzum-tech/design-tokens-resolver';
+
+const resolver = new DesignTokensResolver({ env: 'production' });
+
+const { release, body } = await resolver.fetchVerified({
+  channel: 'latest',
+  collection: 'base-b2b',
+  resolve: true
+});
+
+const document = JSON.parse(body);
+
+for (const token of document.tokens) {
+  // token.path, token.$type, token.$value, token.mode
+}
+
+console.log(`собрано из релиза ${release.version}`);
+```
+
+### Проверка, что токены в репозитории не отстали
+
+```bash
+design-tokens-resolver --channel latest --no-lock --output-path /tmp/tokens
+diff -q /tmp/tokens/tokens.json ./src/tokens/tokens.json
+```
+
+---
+
+## FAQ
+
+**Инстанс создавать один на процесс или на запрос?**
+Как удобно. Состояния между вызовами резолвер не хранит: кеша нет, всё
+живёт в файлах на диске.
+
+**Что коммитить: `tokens.json`, лок или оба?**
+Оба, если токены участвуют в сборке продукта. Тогда сборка
+воспроизводима без сети, а дифф показывает, что именно изменилось.
+Вариант «только лок, а токены — артефакт сборки» тоже рабочий, но тогда
+сборка без движка невозможна.
+
+**Почему в конфиге канал, а не версия?**
+Чтобы решение о выкатке принимала команда дизайн-системы. С версией в
+конфиге проект тихо отстанет от `latest`, и никто этого не заметит.
+
+**Токены с dev попали в prod-сборку — как понять?**
+По локу: в нём лежит `baseUrl`, с которого приехал релиз. Стенд задаёт
+`DESIGN_TOKENS_ENV` или поле `env` в конфиге — искать надо там.
+
+**Сборка упала с `INTEGRITY_MISMATCH` — что делать?**
+Не обходить. Это значит, что байты релиза в базе не совпадают с
+заявленным `contentHash`: либо релиз правили в обход движка, либо ответ
+подменили по дороге. Идти к команде дизайн-системы.
+
+**Движок лежит, а собраться надо.**
+Файлы от прошлого запуска лежат на диске и закоммичены — соберитесь
+напрямую, минуя `prebuild`. `--version` не поможет: номер версии тоже
+берётся с движка.
+
+**Нужен только `tokens.json`, без генерации.**
+Тогда `prebuild: design-tokens-resolver` — и всё; кодогенератор
+появляется по потребности проекта.
+
+**Как посмотреть, что лежит в релизе, ничего не записывая?**
+`fetchVerified()` отдаёт проверенное тело строкой. Из CLI — `--no-lock`
+и `--output-path` во временный каталог.
+
+**Можно ли использовать слои по отдельности?**
+Да, из корня пакета экспортируются `DesignClient`, `HttpClient`,
+`ConfigResolver`, `ConfigFileResolver`, `DocumentMapper`, `LockMapper`,
+`ResolveMapper`, `HashUtils`, `UrlUtils`, `FileUtils`, `ResolveUtils` и
+`ArgsUtils` — если фасад чем-то не подходит, соберите свой из тех же
+деталей.
+
+---
+
+## Разработка
+
+```bash
+pnpm i
+pnpm typecheck
+pnpm lint
+pnpm test
+pnpm build
+```
+
+`pnpm i` ставит husky-хуки. На коммит выполняется `pnpm precommit` —
+`typecheck`, `lint-staged` и тесты параллельно; сообщение коммита
+получает префикс из имени ветки.