umbot/cli/README.md

Мультиплатформенный фреймворк для создания голосовых навыков и чат-ботов с единой бизнес-логикой. Встроенная поддержка ВКонтакте, Telegram, Viber, MAX, Яндекс Алисы, Маруси и Сбера SmartApp. Архитектура на адаптерах позволяет подключать любые другие платф

# CLI утилита umbot для создания голосовых навыков и чат-ботов

**CLI утилита** для быстрого создания и настройки проектов на базе мультиплатформенного фреймворка `umbot`. Позволяет
генерировать готовую структуру для голосовых навыков (Алиса, Маруся, Сбер SmartApp) или чат-ботов (Telegram, VK, Viber, MAX) одной командой.

Также позволяет:

- Создавать новые проекты по готовым шаблонам
- Настраивать конфигурацию проекта
- Генерировать базовую структуру приложения

## 🚀 Быстрый старт

Установите фреймворк и создайте новый проект:

```bash
npx umbot create my-bot
cd my-bot
npm install
npm run build
npm start
```

После этого приложение будет доступно локально. Для тестирования используйте npm run dev (если настроено).

### 📋 Команды CLI

| Команда       | Описание                | Параметры                                 |
| ------------- | ----------------------- | ----------------------------------------- |
| `create`      | Создание нового проекта | `<project-name>` или `<config-file.json>` |
| `generateEnv` | Сгенерировать файл .env | -                                         |

### Флаги команды `create`

| Флаг        | Описание                                                                                                                                                |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--minimal` | Создаёт **минимальный рабочий проект** (один файл, без контроллера и конфигов). Подходит для быстрого прототипа. **Работает только с типом `default`**. |
| `--prod`    | Создаёт production-готовый проект с `Dockerfile`, `.github/workflows/deploy.yml`, `.env`. Удобно для развёртывания на сервере.                          |

> 💡 **Важно**: флаг `--minimal` **не применяется к типу `quiz`**, так как викторина требует сложной логики и хранения
> состояния.

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

#### Простой проект (базовое приложение)

Для быстрого создания приложения, выполните следующую команду

```bash
npx umbot create my-bot-project
```

После выполнения команды, приложение успешно создастся, и останется только выполнить команду:

```bash
npm i
npm run build
npm start
```

#### Проект с конфигурацией из JSON

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

Создайте файл `config.json`

```json
{
    "name": "quiz-bot",
    "type": "quiz",
    "mode": "dev",
    "path": "./bots/quiz",
    "config": {
        "json": "./data",
        "error_log": "./logs",
        "isLocalStorage": true,
        "tokens": {
            "alisa": {
                "token": "..."
            },
            "telegram": {
                "token": "..."
            }
        }
    },
    "isEnv": true
}
```

Затем выполните:

```bash
npx umbot create config.json
```

Утилита создаст проект в папке ./bots/quiz со всеми указанными настройками.

```bash
npm i
npm run build
npm start
```

## ⚙️ Конфигурационный файл (подробно)

### Структура конфигурационного файла

При создании проекта через JSON можно передать следующие параметры:

```ts
interface ProjectConfig {
    // Название проекта (обязательное поле)
    name: string;

    // Тип проекта: "default" или "quiz"
    type?: 'default' | 'quiz';

    // Режим работы: "prod", "dev", "dev-online", "build"
    mode?: 'prod' | 'dev' | 'dev-online' | 'build';

    // Конфигурация приложения (IAppConfig из umbot)
    // В CLI это объект, который будет слит с дефолтным конфигом шаблона.
    config?: Record<string, unknown>;

    // Параметры платформы/интенты (IAppParam из umbot)
    // В CLI это объект, который будет слит с дефолтными params шаблона.
    params?: Record<string, unknown>;

    // Путь для создания проекта
    path?: string;

    // Имя хоста на котором будет запущено приложение. По умолчанию localhost
    hostname?: string;
    // Порт на котором будет запущено приложение. По умолчанию 3000
    port?: number;
    // Определяет нужно создавать .env файл или нет
    isEnv?: boolean;
}
```

### Пример конфигурационного файла

```json
{
    "name": "my-quiz-bot",
    "type": "quiz",
    "mode": "dev",
    "path": "./bots/quiz",
    "config": {
        "json": "./data",
        "error_log": "./logs",
        "isLocalStorage": true,
        "db": {
            "host": "",
            "user": "",
            "pass": "",
            "database": ""
        },
        "tokens": {
            "alisa": {
                "token": "token"
            }
        }
    },
    "isEnv": true
}
```

### Типы проектов

| Тип       | Описание         | Особенности                             |
| --------- | ---------------- | --------------------------------------- |
| `default` | Базовый шаблон   | Минимальная структура проекта           |
| `quiz`    | Шаблон викторины | Готовая структура для создания викторин |

### Режимы работы

| Режим        | Описание                   |
| ------------ | -------------------------- |
| `prod`       | Продакшн режим             |
| `dev`        | Режим разработки           |
| `dev-online` | Режим разработки с webhook |
| `build`      | Режим сборки               |

## Лучшие практики

1. **Именование проектов**:
    - Используйте понятные имена
    - Избегайте пробелов и специальных символов
    - Придерживайтесь kebab-case

2. **Конфигурация**:
    - Храните конфигурацию в отдельных файлах
    - Не включайте чувствительные данные в репозиторий
    - Используйте разные конфигурации для разных окружений

3. **Структура проекта**:
    - Следуйте рекомендуемой структуре
    - Размещайте файлы в соответствующих директориях
    - Документируйте нестандартные решения