@kontur.candy/tools

Все операции выполняются через запуск

Usage no npm install needed!

<script type="module">
  import konturCandyTools from 'https://cdn.skypack.dev/@kontur.candy/tools';
</script>

README

Candy Tools

Перед началом работы

Все операции выполняются через запуск

candy [имя-команды] [...опции]

Имена основных команд:

  • build
  • upgrade
  • dev-build
  • dev-build-server
  • build-server
  • localize
  • init-form
  • form-stats

candy build

Основной сценарий: выполняет сборку форм в каталог с ресурсами. Действия, которые выполняет команда:

  • Получение движка форм версии указанной в form.json,
  • получение генератора форм версии указанной в form.json,
  • генерация и компиляция формы в каталог ресурсов,
  • создание файлов {gfv}.metas.json и presentations.json в каталоге ресурсов
  • копирование конвертеров в каталог ресурсов,
  • копирование схемы в каталог ресурсов.

Опции

  • --watch (-w)

    Watch-режим. Выполняет сборку форм, а затем пересобирает при изменениях. В том числе движка, генератора и статических ресурсов.

  • --clean

    Полностью очищает целевой каталог ресурсов. Используется при полной сборке форм для продакшена

  • --upgrade-form-json

    Форсирует изменение формата файла form.json на новый

  • --build-cache

    Задаёт режим использования кэша сборки. Возможные значения: disabled - не использовать кэш readonly - использовать кэш для сборки, но не обновляеть его (значение по умолчанию) update - использовать кэш для сборки и презаписывать, если не совпадает force-update - всегда выполнять сборку и обновить значения в кэше Отключается при использовании watch-режима

  • --use-last-stable-version

    Уставнавливает версию движка в файла form.json в последнюю стабильную версию. Аналогичен запуску candy-build с параметром -ge master

  • --use-prerelease-version

    Уставнавливает версию движка в файла form.json в последнюю предрелизную версию в заданным preid. В файле версии генератора и движка будут установлены в pre:some-preid.

  • --no-reformat

    Отлючает форматирование генерируемого кода. Работает, только если версия генератора поддерживает эту опцию. Используется для ускорения сборки форм. (default: true)

  • --gfvs (-g)

    Одна или несколько GFV или GFV-масок для пересобрки. Может содержать значки ? и *.

  • --use-version-from-cache

    Использовать версию движка и генератора из файловой системы

  • --development-mode

    Используется только в режиме разработки cli.

  • --verbose (-v)

    Выводить отладочную информацию на консоль.

Примеры использования

# Сборка формы 104816
candy build 104816
# Сборка все формы группы 1
candy build 1?????
# Собрать форму 104816 и сделить за изменениями
candy build 104816 -w
# Использовать последнюю пререлизную версию движка с preid=bso
candy build 104816 --use-prerelease-version bso

Версионирование

При сборке форм, учитывается версия движка и генератора указанные файле form.json. Версии могут указывать не на конкретную версию, а адресовать диапазон в соотвествии с semver. В этом случае будет выбрана последняя подходящая версия.

Файл form.json должен выглядеть следующим образом:

{
    // Опционально
    "themes": ["имя-темы", ...],
    "dependencies": {
        "engine": "[версия-движка]",
        "generator": "[версия-генератора]"
    }
}

версия-движка, версия-генератора - Соответственно, диапазоны версий. На данный момент всегда совпадают.

Допустимые варианты версий:

  • Версия в формате semver.
  • Версия с префиксом pre. Например, pre:my-stange-branch-name, где my-stange-branch-name - название предрелизной версии, выпускаемой разработчиками Candy, для предварительного выпуска форм. Версия с префиксом pre используются для движков, которые не являются стабильными и используются для предварительных сборок форм.

candy upgrade

Обновление формата форм или режима одной или нескольких форм.

Опции

  • --gfvs (-g)

    Одна или несколько GFV или GFV-масок для обновления.

  • --use-ci-build

    Приготовить форму к сборке на CI, без необходимости локальной пересборки.

  • --skip-pre-versions

    При обновлении версий форм не обновлять формы с нестабильными версиями.

  • --engine

    Обновляет движок до заданной версии. Можно использовать кокретную версию движка (например, 0.4.82) или latest, для обновления до последней стабильной версии.

  • --preid

    Обновляет движок до последней пререлизной версии указанной в preid.

  • --development-mode

    Используется только в режиме разработки cli.

  • --verbose (-v)

    Выводить отладочную информацию на консоль.

Примеры использования

Перевод формы на сборку в CI

Выполнить:

candy upgrade --use-ci-build 9900101

Эта команда удалит и заигнорит генерируемые файлы в каталоге farm и поменит форму как собираемую на CI. После этого не требуется далть комиты в репозиторий resources.

Обновлять версию движка формы надо командой:

candy upgrade --engine latest 9900101

candy dev-build

Выполняет сборку форм с ипользованием локальных исходников движка и генератора.

ВАЖНО

Эта команда собирает выполняет сборку форм в каталог ресурсов, но результаты сборки не являеются корректными для выкатывания в продакшен.

Опции

  • --watch (-w)

    Watch-режим. Выполняет сборку форм, а затем пересобирает при изменениях. В том числе движка, генератора и статических ресурсов.

  • --gfvs (-g)

    Одна или несколько GFV или GFV-масок для пересобрки.

  • --skip-generation (-n)

    Не выполнять генарцию формы из сахара, будет выполняться только компиляция исходников формы из каталога форм.

  • --no-reformat

    Отлючает форматирование генерируемого кода. Работает, только если версия генератора поддерживает эту опцию. Используется для ускорения сборки форм.

  • --continue-on-error

    Не генерирует код ошибки в случае ошибки при генерации или компиляции формы.

  • --debug-only (-d)

    Собирать только debug-сборки движка и форм. ВНИМАНИЕ: при работе в браузере необходимо использовать параметр ?debug=true

  • --development-mode

    Используется только в режиме разработки cli.

  • --verbose (-v)

    Выводить отладочную информацию на консоль.

Примеры использования

Написание и просмотр форм

В каталоге candy.farm запустить команды

candy build 123456 -w
candy local-server
  • Переход на url http://localhost:9080/123456/form -- создаст черновик и откроет редактор
  • Inner черновиков находится в каталоге candy.resources/.data

Сборка формы для релиза

candy build 123456

Переключение и сборка формы на использование последней стабильной

candy build 123456 --use-last-stable-version

Затем можно использовать пункт 'Написание и просмотр форм'

Отладка форм с локальным движком

В каталоге candy.farm запустить команды

candy dev-build 123456 -w
candy local-server
  • Переход на url http://localhost:9080/123456/form -- создаст черновик и откроет редактор
  • Inner черновиков находится в каталоге candy.resources/.data

Разработка и отладка движка

В этом случае удобно использовать сборку только отладочных скриптов.

candy dev-build 123456 --watch --debug-only
candy local-server --redirect-to-debug-scripts
  • Переход на url http://localhost:9080/123456/form -- создаст черновик и откроет редактор
  • Inner черновиков находится в каталоге candy.resources/.data

candy dev-build-server

Magic

Опции

  • --gfvs (-g)

    Одна или несколько GFV или GFV-масок для пересобрки.

  • --no-client-override

    Отключает перехват client.js. В этом случае не будет работать отображение логов сборки и ожидания сборки формы.

  • --reformat (-r)

    Включает форматирование генерируемого кода. Работает, только если версия генератора поддерживает эту опцию. Используется для отладки и просмотра сгенерированных форм в отдадчике. (default: false)

  • --debug-only (-d)

    Собирать только debug-сборки движка и форм. ВНИМАНИЕ: при работе в браузере необходимо использовать параметр ?debug=true

  • --development-mode

    Используется только в режиме разработки cli.

  • --verbose (-v)

    Выводить отладочную информацию на консоль.

candy build-server

Magic

Опции

  • --gfvs (-g)

    Опция устарела. Оставлена для обратной совместимости.

  • --nightly

    Включает сборку форм на движке nightly.

  • --no-client-override

    Отключает перехват client.js. В этом случае не будет работать отображение логов сборки и ожидания сборки формы.

  • --reformat (-r)

    Включает форматирование генерируемого кода. Работает, только если версия генератора поддерживает эту опцию. Используется для отладки и просмотра сгенерированных форм в отдадчике. (default: false)

  • --debug-only (-d)

    Собирать только debug-сборки движка и форм. ВНИМАНИЕ: при работе в браузере необходимо использовать параметр ?debug=true

  • --development-mode

    Используется только в режиме разработки cli.

  • --verbose (-v)

    Выводить отладочную информацию на консоль.

candy localize

Локализация формы. Подготавливает текстовые поля в сахаре для перевода и создает словарь

Опции

  • --gfv (-g)

    GFV формы для локализации

  • --dictionary-only (-d)

    Создать словарь локализации без изменения сахара

  • --use-local-generator-sources

    Использовать исходный код генератора из локальной рабочей копии. Используется в режиме разработке.

  • --development-mode

    Используется только в режиме разработки cli.

  • --verbose (-v)

    Выводить отладочную информацию на консоль.

candy init-form

Создание заготовок для новых форм

Опции

  • --gfvs (-g)

    Одна или несколько GFV для которых будет создана заготовка.

  • --development-mode

    Используется только в режиме разработки cli.

  • --verbose (-v)

    Выводить отладочную информацию на консоль.

candy form-stats

Выполняет сборку одной или нескольких форм. Подробнее: https://git.skbkontur.ru/ke/candy-utils/blob/new-candy-tool-cli/README.md

Опции

  • --gfvs (-g)

    Одна или несколько GFV или GFV-масок для пересобрки.

  • --by-engine

    Показать статискиу пе версиям движка.

  • --development-mode

    Используется только в режиме разработки cli.

  • --verbose (-v)

    Выводить отладочную информацию на консоль.