DenoX CLI: Создание проектов и функций без потери контроля

Одной из основных целей DenoX является сокращение повторяющейся разработки без лишения инженеров контроля над процессом. Фреймворк поставляется с собственным CLI в виде единого файла на TypeScript, который позволяет создавать проекты, генерировать полноценные функции, безопасно удалять модули и обновлять сам фреймворк.

В отличие от многих современных CLI, которые используют десятки пакетов, DenoX CLI полностью опирается на встроенные возможности Deno.

Установка

Установить можно одной командой:

deno install -grA -n denox https://raw.githubusercontent.com/olavomello/denox/main/cli/main.ts

Или запустить без установки:

deno run -A https://raw.githubusercontent.com/olavomello/denox/main/cli/main.ts new my-shop

CLI представляет собой самодостаточный файл: нет внешних зависимостей и нет импортов из самого фреймворка.

Создание проекта

Для создания нового приложения достаточно одной команды:

denox new my-shop

Инструмент для создания схемы проекта делает гораздо больше, чем просто сохраняет шаблон на диске. Он загружает официальный стартовый набор, удаляет историю изменений в Git этого набора, создает чистый репозиторий, сбрасывает значение поля версии обратно до 0.1.0, очищает журнал изменений, переписывает файл README с учетом нового названия и соответственно вносит изменения в файл denox.config.ts.

Результат готов к дальнейшей разработке, при этом автоматически проходит проверки deno task ci проекта без необходимости вручную выполнять очистку.

Работают также пользовательские шаблоны:

denox new my-app --template=<repository>

Создание полноценной функциональности

Самое сильное преимущество командной строки — возможность создать целую функциональную часть по принципу MVC с помощью одной команды.

denox g feature reviews

Вместо пустых местоположений генерация создаёт полный фрагмент API в формате MVC: модель и DTO, интерфейс репозитория вместе с реализациями в памяти и через Deno KV, сервис, контроллер, маршруты, описание OpenAPI рядом с кодом и шаблон теста на интеграцию.

Регистрация в src/api/main.ts происходит автоматически, поэтому к функционалу можно получить доступ без ручной настройки.

Встроенное OpenAPI

Каждый сгенерированный функционал имеет своё собственное описание OpenAPI.

Последствия:

• Документация находится рядом с реализацией
• Тесты на паритет маршрутов продолжают проходить
• При запуске:

deno task insomnia

автоматически генерирует коллекцию Insomnia.

Не требуется отдельная ручная работа по поддержке документации API.

Безопасная генерация кода

CLI ведёт себя осторожно при изменении существующего кода.

Когда отсутствует или изменён маркер // denox:features, инструмент отказывается определять точку вставки.

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

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

Удаление функции

Обратная операция имеет такое же значение, как и процесс генерации.

denox rm feature reviews

Удаление разработано для того, чтобы избежать повреждения проектов.

Сначала команная строка удаляет все ссылки на данную функцию в маршрутах.

Файлы удаляются только после того, как приложение полностью отключено от функции.

Даже если процесс прерывается на полпути, в проекте никогда не остаются ссылки на отсутствующие файлы.

По завершении src/api/main.ts возвращается к состоянию до генерации: нет брошенных ссылок и лишних пустых строк.

Предварительный просмотр с использованием:

denox rm feature reviews --dry-run

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

Обновление фреймворка

Для поддержания актуальности проектов используйте:

denox upgrade

При обновлении не перезаписывается весь структурный дерево. Изменяются только пути, принадлежащие фреймворку.

Эти пути приведены явно в файле .denox-core.json.

Всё, что находится вне этого файла, остается нетронутым, включая:

• Сгенерированные функции
• Конфигурация проекта
• Файлы среды
• Код, специфичный для приложения

Дополнительные режимы обновления:

denox upgrade --dry-run
denox upgrade --interactive
denox upgrade --ref=v1.2.0

Перед обновлением интерфейс командной строки проверяет, чист ли рабочий дерево Git. Незакоммитированные изменения прерывают процесс, если только это не запрошено явно, что снижает риск случайной потери данных.

Создание страниц

CLI также поддерживает маршрутизацию на основе файлов в рамках фреймворка.

denox g page docs/faq

или

denox g page items/[id]

После создания страницы таблица маршрутизации автоматически обновляется.

Философия DenoX CLI

CLI соответствует принципам фреймворка: предпочтение устоявшимся правилам перед настройками без потери контроля.

Эти принципы проявляются в конкретных правилах: существующие файлы оставляются без изменений, вручную отредактированные исходники не переписываются, команды с разрушительным эффектом предлагают опцию --dry-run, модули, принадлежащие фреймворку, нельзя удалять бездумно, OpenAPI всегда связан с маршрутами, а файлы фреймворка остаются отдельными от кода приложения.

Все это позволяет создать небольшой и предсказуемый CLI: меньше шаблонного кода, при этом не скрывается то, что было изменено.