@simplegen/simplegen

v0.1.11

Published

14 hours ago

SimpleGen CLI for SimpleOne DSL configuration

Downloads

1,108

0High
0Medium
0Low

simplegen

SimpleGen для SimpleOne

Инструментарий для генерации кода платформы SimpleOne с помощью AI.

Содержание

SimpleGen для SimpleOne

Установка

npm install -g @simplegen/simplegen

Конфигурация

SimpleGen

SimpleGen использует переменные окружения.

Пример создания файла .env в корне репозитория:

SIMPLEONE_URL=http://simple.test
SIMPLEONE_LOGIN=admin
SIMPLEONE_PASSWORD=123456

Должен быть задан либо SIMPLEONE_API_KEY, либо пара SIMPLEONE_LOGIN + SIMPLEONE_PASSWORD.

Источники (по приоритету):

Переменные окружения процесса (SIMPLEONE_*)
.env в корне репозитория
~/.simplegen/.env

Figma MCP-сервер

Для работы с Figma-макетами при создании и модификации виджетов необходимо подключить Figma MCP-сервер. Это позволяет ИИ автоматически извлекать из макетов дизайн-токены, компоненты и структуру UI.

Создайте файл .cursor/mcp.json в корне проекта:

{
  "mcpServers": {
    "figma": {
      "url": "https://mcp.figma.com/mcp"
    }
  }
}

Авторизация Figma:

После добавления конфигурации перезапустите Cursor.
Откройте Cursor Settings → MCP — сервер figma должен отобразиться в списке.
При первом обращении к Figma MCP потребуется авторизация через браузер (OAuth). Следуйте инструкциям в интерфейсе Cursor.

⚠️ Важно: Figma MCP-сервер необязателен для работы с SimpleGen. Он нужен только для задач, связанных с Figma-макетами (виджеты, портальные страницы). Остальные задачи (бизнес-правила, ACL, таблицы и т.д.) работают без него.

Быстрый старт

Если папка проекта ещё не является git-репозиторием, выполните команду:

git init

Запустите инициализацию:

⚠️ Важно: Эту команду стоит применять, когда вы инициализируете пустой репозиторий. При клонировании готового репозитория команду инициализации выполнять не нужно.

simplegen init "Название продукта"

Команда выгрузит все записи с вашего стенда, относящиеся к нужному продукту, а также записи обязательных продуктов (Simple Application и Platform).

💡 Подсказка: Название приложения должно точно совпадать со значением поля name в таблице Applications на вашем стенде.

⚠️ Важно: Выгрузка "тяжёлых" продуктов может занять некоторое время (до 10 минут).

Примечание: Инструмент simplegen init (вызывается через терминал) используется один раз при первичной настройке. Для последующего обновления версий используйте команду /simplegen.init.

Зафиксируйте начальное состояние:

git add .
git commit -m "Initial SimpleGen setup"

Работа над задачей

⚠️ Работа с командами: Команды SimpleGen вызываются через меню / в чате Cursor — начните вводить /simplegen и выберите нужную команду из списка. Не копируйте команды как текст — они не сработают без вызова через /.

Шаг 1. Создание и проверка спецификации

1.1. Создайте спецификацию задачи

Опишите задачу в свободной форме:

/simplegen.spec_create

Название: Валидация поля urgency
Описание: При сохранении task поле urgency должно быть обязательным
Критерии приёмки:
- При пустом urgency показывается ошибка
- Запись не сохраняется без urgency

Если задача связана с UI (виджеты, портальные страницы), включите Figma-ссылку прямо в описание:

/simplegen.spec_create

Название: Массовое завершение инцидентов
Описание: Добавить виджет массового завершения инцидентов из списка
[(см. макет)](https://www.figma.com/design/XXXXX/Project?node-id=123-456&m=dev)
Критерии приёмки:
- Пользователь выбирает записи в списке и нажимает «Завершить»
- Открывается модальное окно с полями из макета
- При подтверждении записи переходят в статус «Завершено»

💡 Подсказка: При наличии Figma-ссылки в описании ИИ автоматически обратится к макету через Figma MCP, извлечёт компоненты, дизайн-токены и структуру UI, и включит их в спецификацию. Подробнее — в разделе Работа с Figma-макетами.

Что произойдёт:

Создастся каталог tasks/<task_id>/ (если указан идентификатор задачи — используется он, иначе slug генерируется автоматически из названия задачи)
Появится файл _spec.md с постановкой задачи
Появится simplegen.json с метаданными
Появится каталог build_logs/ для артефактов сборки
Если в описании была Figma-ссылка — в _spec.md будут включены элементы, извлечённые из макета

1.2. Проверьте постановку задачи в спецификации

/simplegen.spec_check

AI задаст уточняющие вопросы и поможет выявить неоднозначности в требованиях.

Шаг 2. Планирование реализации

2.1. Создайте план реализации

/simplegen.spec_plan

Команда разобьёт задачу на фазы и создаст план выполнения в файле _task.md.

2.2. Закоммитьте спецификацию

git add .
git commit -m "Add spec for <feature>"

Шаг 3. Генерация кода

3.1. Сгенерируйте код

/simplegen.code_generate

ИИ выполняет кодогенерацию по плану _task.md и спецификации _spec.md активной фичи.

На выходе:

Файлы DSL в <product>/domain/ — таблицы, колонки, бизнес-правила, клиентские скрипты, UI Actions и другие сущности
Скрипты .js с бизнес-логикой
TypeScript-файлы records.ts с метаданными записей

Команду можно вызывать несколько раз (например, по фазам _task.md) — изменения накапливаются поверх текущего состояния кода.

💡 Работа с изменениями в Cursor:
После генерации кода Cursor покажет предложенные изменения в панели Changes.
Keep All — принять все изменения (или кликните на файл и нажмите Ctrl+Shift+Enter)
Reject All — отклонить все изменения
Кликните на конкретный файл, чтобы просмотреть diff и принять/отклонить изменения точечно

3.2. Проведите code review

/simplegen.code_review

Автоматическая проверка сгенерированного кода на соответствие правилам и рекомендациям.

💡 Рекомендация: Code review не является обязательным, но настоятельно рекомендуется перед деплоем для выявления потенциальных проблем.

Если review обнаружил ошибки:

Исправьте код через чат (опишите ошибку и попросите ИИ внести правки), затем повторите /simplegen.code_review
Если точечные правки не помогают — перегенерируйте код через /simplegen.code_generate (будет создан новый DSL)

3.3. Закоммитьте результат

git add .
git commit -m "Implement <feature>"

Шаг 4. Деплой на стенд

/simplegen.product_build

Команда соберёт SOP-файл и развернёт изменения на вашем стенде SimpleOne. Статус деплоя будет выведен в консоль.

Работа с Figma-макетами

SimpleGen поддерживает работу с Figma-макетами через MCP-сервер Figma. Это позволяет ИИ обращаться к макетам напрямую — извлекать компоненты, дизайн-токены, типографику, цвета и структуру UI, и использовать их при генерации виджетов.

⚠️ Предварительное условие: Figma MCP-сервер должен быть настроен (см. Figma MCP-сервер).

Как включить макет в задачу

Включите Figma-ссылку в описание задачи при вызове /simplegen.spec_create. Поддерживаемые форматы ссылок:

https://www.figma.com/design/<FILE_KEY>/<FileName>?node-id=<NODE_ID>&m=dev
https://www.figma.com/file/<FILE_KEY>/<FileName>?node-id=<NODE_ID>

Ссылку можно включить двумя способами:

Inline — прямо в тексте описания:

Описание: Добавить модальное окно массового завершения
[(см. макет)](https://www.figma.com/design/XXXXX/Project?node-id=123-456&m=dev)

В отдельном разделе — если макетов несколько:

Описание: Новая страница каталога услуг

Макеты:
- Основной вид: https://www.figma.com/design/XXXXX/Project?node-id=100-200&m=dev
- Состояние пустого списка: https://www.figma.com/design/XXXXX/Project?node-id=100-300&m=dev
- Мобильная версия: https://www.figma.com/design/XXXXX/Project?node-id=100-400&m=dev

💡 Подсказка: Ссылку на макет можно получить в Figma: правый клик на фрейм → Copy/Paste as → Copy link. Для режима разработки откройте фрейм и скопируйте URL из адресной строки.

Что происходит при обработке макета

При обнаружении Figma-ссылки ИИ автоматически:

На этапе спецификации (spec_create, spec_check):
- Извлекает из макета элементы UI: поля ввода, кнопки, списки, секции
- Определяет логику взаимодействия: переходы между состояниями, условную видимость
- Документирует всё это в _spec.md
На этапе генерации кода (code_generate):
- Маппит Figma-компоненты на SimpleTags платформы (<string>, <select>, <reference> и др.)
- Извлекает дизайн-токены и транслирует их в CSS-переменные SimpleOne (var(--token))
- Генерирует код виджета (HTML-шаблон, CSS, клиентский и серверный скрипты)

💡 Подсказка: Если ваш Figma MCP-сервер недоступен, вы можете вложить скриншот макета прямо в чат Cursor как изображение. ИИ проанализирует его визуально, но точность извлечения дизайн-токенов будет ниже.

FAQ: Решение типичных вопросов

Как посмотреть текущую фичу?
→ Откройте simplegen.json в корне продукта и найдите поле current_feature_path

Как переключиться между фичами?
→ Выполните /simplegen.context_set tasks/<task_id>

⚠️ Одновременно работать над несколькими фичами нельзя. Если не переключиться, модель будет видеть старую фичу, но контекст будет нарушен новой задачей — это приведёт к ошибкам в коде и спецификации.

Как принять или отклонить изменения после генерации?
→ После выполнения /simplegen.code_generate Cursor покажет изменения в панели Changes
→ Keep All — принять все предложенные изменения
→ Reject All — отклонить все изменения
→ Кликните на файл для просмотра diff и точечного принятия/отклонения

Как откатить изменения?
→ /simplegen.product_rollback — откат SOP на стенде (возврат к последнему успешному деплою)
→ git reset --hard HEAD~1 — откат на предыдущий коммит локально
→ git checkout . — отмена незакоммиченных изменений

Нужно синхронизировать с сервером?
→ Выполните /simplegen.product_sync — обновление platform/, sa/, domain/

Нужно обновить версию SimpleGen?
→ Выполните /simplegen.init — переинициализация на уже настроенном проекте

⚠️ Внимание: Команда перезапишет локальные изменения в domain/. Убедитесь, что все изменения закоммичены или сохранены.

Ошибка версий перед операцией?
→ Если server_platform_version > local_platform_version или server_product_version > local_product_version, выполните /simplegen.product_sync

Figma MCP-сервер не подключается?
→ Проверьте наличие файла .cursor/mcp.json с записью "figma" (см. Figma MCP-сервер)
→ Перезапустите Cursor после добавления конфигурации
→ Проверьте статус в Cursor Settings → MCP — сервер figma должен быть в списке
→ Если статус красный — нажмите на сервер и пройдите повторную авторизацию

ИИ не обращается к макету при создании спецификации?
→ Убедитесь, что Figma-ссылка включена непосредственно в описание задачи при /simplegen.spec_create
→ Ссылка должна быть в формате https://www.figma.com/design/<FILE_KEY>/...?node-id=<NODE_ID>
→ Проверьте, что Figma MCP-сервер доступен (см. выше)

Справочные материалы

Все команды

Инициализация и настройка

| Команда | Назначение | | ------- | ---------- | | /simplegen.init | (Пере)инициализация — обновляет platform/, sa/, domain/, правила | | /simplegen.product_sync | Синхронизировать со стендом (при расхождении версий) | | /simplegen.context_set | Установить активную фичу |

Работа со спецификацией

| Команда | Назначение | | ------- | ---------- | | /simplegen.spec_create | Создать фичу из описания задачи | | /simplegen.spec_check | Проверить постановку, задать уточняющие вопросы | | /simplegen.spec_plan | Разбить задачу на фазы → _task.md |

Генерация и review

| Команда | Назначение | | ------- | ---------- | | /simplegen.code_generate | Генерация кода по плану | | /simplegen.code_review | Review изменений (diff initial_commit..HEAD) |

Сборка и деплой

| Команда | Назначение | | ------- | ---------- | | /simplegen.product_build | Собрать SOP-файл, задеплоить на стенд | | /simplegen.product_rollback | Откатить на предыдущий SOP-файл |

Форматы описания задач

User Story

Название: [название]
Описание: [описание]
Критерии приёмки:
- [критерий 1]
- [критерий 2]

User Story с макетом

Название: [название]
Описание: [описание]
[(см. макет)](https://www.figma.com/design/XXXXX/Project?node-id=123-456&m=dev)
Критерии приёмки:
- [критерий 1]
- [критерий 2]

💡 Figma-ссылку можно включить в любое место описания. ИИ автоматически обнаружит её и извлечёт данные из макета. Подробнее — Работа с Figma-макетами.

Defect

Название: [название]
Описание: [описание]
Шаги воспроизведения:
1. [шаг]
Ожидаемый: [...]
Фактический: [...]

Свободная форма

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

Структура проекта

workspace-root/
├── AGENTS.md                  # 📄 Глобальный контекст проекта (краткое описание приложений)
├── platform/                  # 🔒 Read-only — платформа SimpleOne
├── sa/                        # 🔓/🔒 Simple Application (🔓 при X-SimpleOne-Vendor: true)
├── .cursor/
│   ├── mcp.json               # ⚙️ MCP-серверы (Figma, SimpleOne)
│   ├── rules/                 # Правила кодогенерации (управляются simplegen.init)
│   └── commands/              # Команды /simplegen.* (управляются simplegen.init)
│
└── <product>/                 # 📦 Ваш продукт (itsm/, hrm/, etc.)
    ├── AGENTS.md              # 📄 Контекст продукта (краткое описание приложения)
    ├── simplegen.json         # ⚙️ Конфигурация продукта
    ├── tests/                 # 🧪 Автотесты
    ├── domain/                # Бизнес-конфигурация решения
    │   ├── data-structure/    # Таблицы, колонки, справочники, состояния
    │   ├── business-logic/    # Бизнес-правила, клиентские скрипты, UI Actions
    │   │   ├── business-rules/<table_name>/  # records.ts + <script_name>.js
    │   │   ├── client-scripts/<table_name>/  # records.ts + <script_name>.js
    │   │   ├── ui-actions/<table_name>/      # records.ts + <script_name>.js
    │   │   └── system-properties.ts
    │   ├── access-control/    # Роли, ACL
    │   │   ├── roles.ts
    │   │   └── security-acls/<table_name>/   # records.ts + <script_name>.js
    │   ├── forms/             # Представления форм (<table_name>/views.ts, sections.ts, elements.ts)
    │   ├── lists/             # Списки (<table_name>/views.ts, related-lists.ts)
    │   ├── rem/                # REM — расширенная модель записи
    │   │   ├── models/<table_name>/           # SysReModel (records.ts + <script_name>.js)
    │   │   ├── client-scripts/<container_name>/  # SysReModelClientScript (records.ts + <script_name>.js)
    │   │   ├── form-elements/<container_name>.ts # SysReFormElement
    │   │   ├── attributes/<container_name>.ts # SysReAttribute
    │   │   ├── choices/<attribute_name>.ts    # SysReChoice
    │   │   ├── collections.ts                 # SysReCollection
    │   │   └── containers.ts                  # SysReContainer
    │   ├── schedule/           # Планировщик (календари, элементы, задания)
    │   │   ├── scheduled-scripts/<table_name>/  # records.ts + <script_name>.js
    │   │   ├── schedule-elements.ts
    │   │   ├── scheduled-jobs.ts
    │   │   ├── scheduled-imports.ts
    │   │   └── schedules.ts
    │   ├── navigation/        # Навигация (menu-items.ts, menu-categories.ts)
    │   ├── service-catalog/   # Каталог услуг (sys_rmc_catalog.ts, sys_rmc_category.ts, ...)
    │   ├── portal/            # Портал (page.ts, page_container.ts, page_row.ts, page_column.ts, portal.ts, sys_portal_context.ts, portal_node.ts)
    │   ├── other/             # Все остальные верионируемые сущности
    │   └── localization/      # Локализации
    │       ├── languages.ts
    │       ├── source-messages/<slug>/  # source.ts + messages.ts
    │       └── translations/<table_name>/  # <column_name>.ts
    │
    └── tasks/                          # Задачи
        └── <task_id>/                  # идентификатор из трекера или slug
            ├── _spec.md                # Постановка задачи
            ├── _task.md                # План выполнения задачи
            ├── simplegen.json          # Метаданные задачи
            ├── [<PRODUCT>]_<task_id>.sop  # Текущий SOP (обновляется при билде)
            └── build_logs/             # Архив SOP, логи API (gitignore)

Поддерживаемые сущности

sys_db_table
sys_db_column
sys_choice
sys_security_acl
sys_ui_form
- sys_ui_form_section
- sys_ui_form_element
- sys_ui_related_list
- sys_ui_related_list_element
sys_business_rule
sys_script_client
sys_ui_action
source_message
- message
sys_language
sys_translation
sys_property
sys_number
sys_ui_list
sys_filter_option_dynamic
sys_script_include
sys_notification_rule
sys_notification_script
sys_notification_template
sys_widget
sys_widget_instance
sys_menu_category
sys_menu_item
sys_user_criteria
sys_re_model
sys_re_collection
sys_re_attribute
sys_re_choice
sys_re_model_client_script
sys_re_form_element
page
page_container
page_row
page_column
portal
sys_portal_context
portal_node
sys_rmc_catalog
sys_rmc_category
sys_rmc_model
sys_rmc_category_user_criteria
sys_rmc_model_user_criteria
sys_schedule
sys_schedule_element
sys_schedule_job
sys_schedule_import
sys_schedule_script

Остальные сущности экспортируются в папку other, но не поддерживаются правилами.