Metadata-Version: 2.4
Name: cicada-studio
Version: 0.0.1
Summary: Русский DSL для Telegram ботов
Author: Cicada Team
License: MIT
Project-URL: Homepage, https://github.com/cicada-team/cicada-studio
Project-URL: Repository, https://github.com/cicada-team/cicada-studio
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Dynamic: license-file

# 🦋 Cicada

> **Русский язык программирования для создания Telegram-ботов**

[![Python](https://img.shields.io/badge/Python-3.9%2B-blue)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![PyPI version](https://img.shields.io/pypi/v/cicada-studio.svg)](https://pypi.org/project/cicada-studio)
[![Downloads](https://img.shields.io/pypi/dm/cicada-studio.svg)](https://pypi.org/project/cicada-studio)
[![Tests](https://github.com/yourname/cicada-studio/actions/workflows/tests.yml/badge.svg)](https://github.com/yourname/cicada-studio/actions)
[![Coverage](https://img.shields.io/codecov/c/github/yourname/cicada-studio.svg)](https://codecov.io/gh/yourname/cicada-studio)
[![Stars](https://img.shields.io/github/stars/yourname/cicada-studio.svg?style=social)](https://github.com/yourname/cicada-studio)

Cicada — это предметно-ориентированный язык (DSL), позволяющий писать ботов для Telegram на **чистом русском языке**. Никакого boilerplate-кода, никакой сложной асинхронности — только логика вашего бота.

---

## � Установка

### Из PyPI (рекомендуется)

```bash
pip install cicada-studio
```

### Из исходников

```bash
git clone https://github.com/Cicadadenis/cicada-studio.git
cd cicada-studio
pip install -e .
```

---

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

### Первый бот за 30 секунд

Создайте файл `привет.ccd`:

```cicada
бот "ВАШ_ТОКЕН_ЗДЕСЬ"

при старте:
    ответ "Привет! Я ваш первый бот на Cicada 👋"
    кнопки "Статус" "Помощь"

если текст == "Статус":
    ответ "Всё работает отлично! ✅"

если текст == "Помощь":
    ответ "Напишите что угодно, я повторю."

иначе:
    ответ "Вы написали: " + текст
```

Запустите:

```bash
cicada run привет.ccd
```

---

## 🤔 Почему Cicada?

Cicada создана чтобы **упростить** разработку Telegram-ботов. Никакой сложности — только ваша логика.

### 🎯 Решаемые проблемы

| ❌ Было | ✅ Стало |
|---------|----------|
| **Сложность Telegram API** — куча методов, вебхуки, поллинг | Декларативный DSL: `ответ`, `кнопки`, `спросить` |
| **Асинхронность Python** — callback'и, asyncio, await | Синхронный код, скрытая асинхронность |
| **FSM логика** — сложные state machine, transitions | Встроенные сценарии: `сценарий`, `шаг`, `повторить шаг` |
| **Boilerplate код** — 50+ строк настройки | 10 строк — и бот работает |

### 👥 Кому подходит

- 🛒 **Магазины** — каталоги, корзина, заказы, оплата
- 💬 **Поддержка** — тикеты, FAQ, чаты с операторами
- 📢 **Маркетинг** — рассылки, опросы, розыгрыши, игры
- 🏢 **CRM** — автоматизация бизнес-процессов, интеграции
- 🤖 **Чат-боты** — любые диалоговые сценарии, анкеты, боты-ассистенты

### 📊 Сравнение

```python
# python-telegram-bot: ~50 строк
from telegram import Update, ReplyKeyboardMarkup
from telegram.ext import Application, CommandHandler, ContextTypes

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text("Привет!")

app = Application.builder().token("TOKEN").build()
app.add_handler(CommandHandler("start", start))
app.run_polling()

# Aiogram: ~40 строк
from aiogram import Bot, Dispatcher, types
bot = Bot(token="TOKEN")
dp = Dispatcher()

@dp.message(Command("start"))
async def cmd_start(message: types.Message):
    await message.answer("Привет!")

# Cicada: 10 строк
бот "TOKEN"
при старте:
    ответ "Привет!"
```

| Решение | Код для эхо-бота | Сложность | FSM |
|---------|------------------|-----------|-----|
| python-telegram-bot | ~50 строк | Высокая | Ручная |
| Aiogram | ~40 строк | Средняя | Ручная |
| **Cicada** | **10 строк** | **Низкая** | **Встроена** |

---

## 🏗️ Архитектура

```
┌─────────────────────────────────────────────────────────────┐
│                      Пользователь                            │
│                         (Telegram)                          │
└────────────────────┬────────────────────────────────────────┘
                     │ HTTP
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                   Telegram API                               │
│              (BotFather Token)                              │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                    Cicada Runtime                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   Parser     │→ │     AST      │→ │   Executor   │       │
│  │  (.ccd →)    │  │  (дерево)    │  │  (TG API)    │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
│         │                 │                 │               │
│         ▼                 ▼                 ▼               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   Blocks   │  │   Runtime    │  │  Database    │       │
│  │   (globals)│  │ (user ctx)   │  │  (JSON)      │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└─────────────────────────────────────────────────────────────┘
```

**Компоненты:**
- **Parser** — преобразует `.ccd` в AST
- **AST** — абстрактное синтаксическое дерево
- **Executor** — выполняет команды через Telegram API
- **Runtime** — контекст пользователя, переменные
- **Database** — JSON-хранилище состояния

---

## 💻 CLI (Командная строка)

### Основные команды

```bash
# Запуск бота
cicada run bot.ccd

# Режим разработки с подробным выводом
cicada run bot.ccd --debug
cicada run bot.ccd --dev

# Автоперезагрузка при изменении файлов
cicada run bot.ccd --reload

# Проверка синтаксиса без запуска
cicada check bot.ccd

# Инициализация нового проекта
cicada init my-bot
cd my-bot
cicada run bot.ccd
```

### Глобальные флаги

```bash
# Показать версию
cicada --version

# Справка
cicada --help
cicada run --help
```

### Переменные окружения

```bash
# Токен можно передать через env
export CICADA_TOKEN="your:token"

# Режим отладки
export CICADA_DEBUG=1

# Путь к конфигу
export CICADA_CONFIG="./config.yaml"
```

---

## 🎯 Примеры проектов

В папке [`examples/`](./examples) собраны готовые шаблоны:

| Пример | Описание | Сложность |
|--------|----------|-----------|
| [`echo.ccd`](./examples/echo.ccd) | Эхо-бот с кнопками | ⭐ Лёгкая |
| [`shop.ccd`](./examples/shop.ccd) | Магазин с корзиной | ⭐⭐ Средняя |
| [`support.ccd`](./examples/support.ccd) | Система тикетов | ⭐⭐⭐ Сложная |

### Быстрый старт с примерами

```bash
# Клонируем
git clone https://github.com/Cicadadenis/cicada-studio.git
cd cicada-studio

# Устанавливаем
pip install -e .

# Запускаем пример
cd examples
cicada echo.ccd --debug
```

---

## 📖 Синтаксис языка

### Объявление бота

```cicada
бот "ВАШ_TELEGRAM_ТОКЕН"
```

### Обработчики событий

| Конструкция | Описание |
|-------------|----------|
| `при старте:` | Команда `/start` |
| `при команде "/команда":` | Любая команда |
| `если текст == "...":` | Условие по точному совпадению |
| `если текст содержит "...":` | Проверка подстроки |
| `иначе:` | Блок по умолчанию |

### Ответы и действия

```cicada
# Простой текст
ответ "Привет, мир!"

# С переменными
ответ "Привет, " + имя + "!"

# Инлайн-кнопки
кнопки "Да" "Нет" "Отмена"

# Изображение
картинка "https://example.com/photo.jpg"

# Стикер
стикер "CAACAgIAAxkBAA..."
```

### Переменные и память

```cicada
# Сохранение значения
запомни город = "Москва"
запомни счётчик = 42

# Использование в ответах
ответ "Вы выбрали: " + город
```

### 👤 Объект пользователя

Доступ к данным пользователя через точку:

```cicada
ответ "Ваш ID: " + пользователь.id
ответ "Имя: " + пользователь.имя
ответ "Фамилия: " + пользователь.фамилия
```

Доступные свойства: `id`, `имя`, `фамилия`, `chat_id`

### 🔤 Функции для работы со строками

```cicada
# Проверка содержимого
если содержит(текст, "купить"):
    ответ "Напишите что хотите купить"

# Проверка длины
если длина(текст) > 100:
    ответ "Слишком длинное сообщение!"

# Проверка начала строки
если начинается_с(текст, "/"):
    ответ "Это команда"
```

### 🔗 Логические операторы в условиях

```cicada
# ИЛИ — хотя бы одно условие
если текст == "да" или текст == "yes":
    ответ "Согласие получено!"

# И — все условия
если содержит(текст, "бонус") и длина(текст) > 10:
    ответ "Написано про бонус и подробно"

# НЕ — отрицание
если не текст == "exit":
    ответ "Продолжаем..."

# Числовые сравнения
если баланс > 100:
    ответ "У вас достаточно средств"
```

---

## 🎯 Сценарии (FSM)

Cicada поддерживает многошаговые диалоги (анкеты) через `сценарий`:

```cicada
при команде "/анкета":
    запустить регистрация

сценарий регистрация:
    спросить "Как вас зовут?" → имя
    запомни имя_пользователя = имя
    
    спросить "Сколько вам лет?" → возраст
    запомни возраст_пользователя = возраст
    
    ответ "Приятно познакомиться, " + имя_пользователя + "!"
    ответ "Вам " + возраст_пользователя + " лет. Записано ✅"
```

Каждый `спросить` приостанавливает бота и ждёт ответа пользователя, сохраняя его в указанную переменную.

### 🎯 Именованные шаги в сценариях

```cicada
сценарий регистрация:
    шаг имя:
        спросить "Как вас зовут?" → имя
        сохранить "имя" = имя
    
    шаг возраст:
        спросить "Сколько вам лет?" → возраст
        если возраст < 18:
            ответ "Извините, только для взрослых"
            завершить сценарий
    
    ответ "Регистрация завершена!"
```

### 💾 База данных (постоянное хранение)

Данные сохраняются между сессиями:

```cicada
# Сохранить значение
сохранить "баланс" = 1000
сохранить "уровень" = уровень

# Получить значение
получить "баланс" → баланс
получить "уровень" → текущий_уровень

ответ "Ваш баланс: " + баланс
```

### 🔘 Кнопки с callback

```cicada
бот "ТОКЕН"

при старте:
    кнопка "Купить" -> "buy"
    кнопка "Сайт" -> url "https://example.com"

при нажатии "buy":
    ответ "Вы нажали купить!"
    сохранить "покупок" = покупок + 1
```

### 🌍 HTTP API клиент

```cicada
бот "ТОКЕН"

при команде "/курс":
    http_get "https://api.exchangerate.host/latest?base=USD" → данные
    ответ "Курс получен!"
    лог данные

при команде "/отправить":
    http_post "https://hooks.slack.com/..." с "Привет!" → ответ
    ответ "Отправлено!"
```

### 📦 Пакеты и модули

```cicada
версия "1.0"
бот "ТОКЕН"

# Импорт пакета из cicada_modules/shop/index.ccd
импорт "cicada.shop"
импорт "cicada.auth"

старт:
    использовать приветствие_магазина
```

### 🧱 Переиспользуемые блоки

```cicada
бот "ТОКЕН"

# Определяем блок для переиспользования
блок приветствие:
    ответ "Привет, {имя}! 👋"
    кнопки "Каталог" "Корзина"

старт:
    использовать приветствие

при нажатии "Каталог":
    использовать приветствие
    ответ "Вот наш каталог:"
```

### 🎯 Валидация в FSM сценариях

```cicada
сценарий регистрация:
    шаг возраст:
        спросить "Сколько вам лет?" → возраст
        если не число(возраст):
            ответ "Пожалуйста, введите число!"
            повторить шаг
        если возраст < 18:
            ответ "Извините, только для взрослых"
            завершить сценарий
    
    шаг email:
        спросить "Введите email:" → email
        если не содержит(email, "@"):
            ответ "Некорректный email!"
            повторить шаг
```

### 🌐 Middleware (до/после каждого сообщения)

```cicada
бот "ТОКЕН"

# Выполняется перед каждым сообщением
до каждого:
    лог "Пользователь {пользователь.имя} написал: {текст}"
    получить "посещений" → счётчик
    запомни счётчик = счётчик + 1
    сохранить "посещений" = счётчик

# Выполняется после каждого сообщения
после каждого:
    если счётчик > 10:
        ответ "Вы активный пользователь! 🌟"

старт:
    ответ "Добро пожаловать!"
```

### 💰 Типы данных и переменные

```cicada
# Разные типы данных
пусть баланс = 1000                    # число
пусть активен = истина                 # логический
пусть бан = ложь                       # логический
пусть товары = ["A", "B", "C"]         # массив
пусть цены = [100, 200, 300]          # массив чисел

# Глобальная переменная (доступна всем)
глобально админ_id = 123456

# Проверка типов
если тип(баланс) == "число":
    ответ "Баланс корректен"

если активен == истина:
    ответ "Аккаунт активен"
```

### 🔀 Навигация в сценариях

```cicada
сценарий мастер_настройки:
    шаг язык:
        спросить "Выберите язык (ru/en):" → язык
        если язык == "en":
            сохранить "lang" = "en"
            перейти к шаг готов
        сохранить "lang" = "ru"
    
    шаг уведомления:
        спросить "Включить уведомления? (да/нет)" → ответ
        если ответ == "да":
            сохранить "notif" = истина
        иначе:
            сохранить "notif" = ложь
            вернуть  # выходим из шага, но сценарий продолжается
    
    шаг готов:
        ответ "Настройка завершена!"
```

### 📸 Обработка медиа и файлов

```cicada
# При получении фото
при фото:
    получить "фото_счет" → счет
    запомни счет = счет + 1
    сохранить "фото_счет" = счет
    ответ "📸 Получено фото #{счет}"
    переслать фото "Спасибо за фото!"

# При получении документа
при документ:
    ответ "📄 Получен файл: {имя_файла}"
    ответ "Размер: {размер_файла} байт"

# При получении голосового сообщения
при голос:
    ответ "🎤 Голосовое получено!"
    # Сохраняем file_id для дальнейшей обработки
    сохранить "voice_id" = файл_id

# При получении локации
при локации:
    ответ "📍 Получены координаты:"
    ответ "Широта: {широта}"
    ответ "Долгота: {долгота}"

# При получении контакта
при контакте:
    ответ "👤 Контакт получен:"
    ответ "Имя: {имя_контакта}"
    ответ "Телефон: {телефон_контакта}"
```

### 🎨 Полный пример бота магазина

```cicada
версия "1.0"
бот "ВАШ_ТОКЕН"

# Команды меню Telegram
команды:
    "/start" - "Запуск бота"
    "/catalog" - "Каталог товаров"
    "/cart" - "Корзина"
    "/support" - "Поддержка"

# Глобальные настройки
глобально магазин_открыт = истина
глобально админ_id = 123456789

# Блок приветствия
блок приветствие:
    ответ "👋 Привет, {пользователь.имя}!"
    ответ "Добро пожаловать в наш магазин"
    кнопки "Каталог 🛍" "Корзина 🛒" "Поддержка 💬"

старт:
    если не магазин_открыт:
        ответ "🚫 Магазин временно закрыт"
        вернуть
    использовать приветствие

команда "/catalog":
    запустить каталог

команда "/cart":
    получить "cart" → корзина
    если тип(корзина) != "массив":
        ответ "🛒 Корзина пуста"
    иначе:
        ответ "🛒 В корзине {длина(корзина)} товаров"

при нажатии "Каталог 🛍":
    использовать приветствие

при нажатии "Поддержка 💬":
    запустить поддержка

# FSM сценарий каталога
сценарий каталог:
    шаг выбор:
        ответ "📦 Доступные товары:"
        кнопка "Товар A - 100₽" -> "buy_a"
        кнопка "Товар B - 200₽" -> "buy_b"
        кнопка "Назад" -> "back"
    
    шаг подтверждение:
        спросить "Введите количество:" → количество
        если не число(количество):
            ответ "❌ Введите число!"
            повторить шаг
        если количество < 1:
            ответ "❌ Минимум 1 штука!"
            повторить шаг
        ответ "✅ Добавлено в корзину"

# Сценарий поддержки
сценарий поддержка:
    шаг вопрос:
        спросить "Опишите вашу проблему:" → вопрос
        если длина(вопрос) < 10:
            ответ "❌ Описание слишком короткое"
            повторить шаг
        ответ "📨 Ваш вопрос принят! Ответим в течение 24 часов."
        лог "Новый тикет от {пользователь.имя}: {вопрос}"
```

---

## 💡 Примеры

### Эхо-бот

```cicada
бот "ТОКЕН"

при старте:
    ответ "Напишите мне что-нибудь!"

иначе:
    ответ "Вы: " + текст
```

### Бот с меню

```cicada
бот "ТОКЕН"

при старте:
    ответ "🤖 Главное меню"
    кнопки "Погода" "Новости" "Настройки"

если текст == "Погода":
    ответ "☀️ Сегодня солнечно, +25°C"

если текст == "Новости":
    ответ "📰 Последние новости..."

если текст == "Настройки":
    ответ "⚙️ Настройки профиля"
```

### Бот-опросник

```cicada
бот "ТОКЕН"

при команде "/опрос":
    запустить опрос

сценарий опрос:
    спросить "Оцените сервис от 1 до 5:" → оценка
    спросить "Что можно улучшить?" → отзыв
    
    ответ "Спасибо за оценку " + оценка + "!"
    ответ "Ваш отзыв: " + отзыв
```

---

## 🛠️ Установка и требования

- **Python:** 3.9 или выше
- **Зависимости:** `requests`
- **Токен:** Получите у [@BotFather](https://t.me/botfather) в Telegram

---

## 📚 Полный справочник команд

| Команда | Пример | Описание |
|---------|--------|----------|
| `бот` | `бот "TOKEN"` | Установка токена |
| `при старте:` | `при старте: ответ "Hi"` | Обработка /start |
| `при команде` | `при команде "/help":` | Обработка команд |
| `ответ` | `ответ "Текст" + переменная` | Отправка сообщения |
| `кнопки` | `кнопки "A" "B" "C"` | Инлайн-кнопки |
| `если` | `если текст == "X":` | Условие |
| `иначе:` | `иначе: ответ "..."` | Ветка по умолчанию |
| `сценарий` | `сценарий имя:` | Объявление FSM |
| `запустить` | `запустить имя` | Начало сценария |
| `спросить` | `спросить "Вопрос?" → переменная` | Вопрос пользователю |
| `запомни` | `запомни x = значение` | Сохранение в память |
| `картинка` | `картинка "url"` | Отправка фото |
| `стикер` | `стикер "file_id"` | Отправка стикера |
| **Медиа** |||
| `документ` | `документ "file.pdf" "Подпись"` | Отправка файла |
| `аудио` | `аудио "song.mp3"` | Отправка аудио |
| `видео` | `видео "clip.mp4"` | Отправка видео |
| `голос` | `голос "voice.ogg"` | Голосовое сообщение |
| `локация` | `локация 55.75 37.61` | Отправка координат |
| `контакт` | `контакт "Имя" "+7999..."` | Отправка контакта |
| `опрос` | `опрос "Вопрос?" "Да" "Нет"` | Создание опроса |
| `игра` | `игра "game_short_name"` | Игра |
| `ответ_md` | `ответ_md "**жирный**"` | Markdown форматирование |
| **Логика** |||
| `и` | `если А и Б:` | Логическое И |
| `или` | `если А или Б:` | Логическое ИЛИ |
| `не` | `если не А:` | Отрицание |
| **Строки** |||
| `содержит()` | `содержит(текст, "X")` | Проверка подстроки |
| `длина()` | `длина(текст) > 5` | Длина строки |
| `начинается_с()` | `начинается_с(текст, "/")` | Проверка префикса |
| **БД** |||
| `сохранить` | `сохранить "ключ" = X` | Сохранить в БД |
| `получить` | `получить "ключ" → перем` | Загрузить из БД |
| **Получение медиа** |||
| `при фото:` | `при фото:` | Обработка фото |
| `при документ:` | `при документ:` | Обработка файлов |
| `при голос:` | `при голос:` | Голосовые сообщения |
| `при локации:` | `при локации:` | Геолокация |
| `при контакте:` | `при контакте:` | Контакты |
| **FSM** |||
| `шаг` | `шаг имя:` | Именованный шаг |
| `завершить` | `завершить сценарий` | Прервать сценарий |
| **HTTP** |||
| `http_get` | `http_get "url" → ответ` | GET-запрос |
| `http_post` | `http_post "url" с "data" → ответ` | POST-запрос |
| **Кнопки** |||
| `кнопка` | `кнопка "Текст" -> "callback"` | Кнопка с callback |
| `кнопка URL` | `кнопка "Сайт" -> url "..."` | Кнопка с ссылкой |
| `при нажатии` | `при нажатии "buy":` | Обработчик кнопки |
| **Утилиты** |||
| `подождать` | `подождать 2` | Задержка в секундах |
| `лог` | `лог "сообщение"` | Вывод в консоль |
| **API** |||
| `tg` | `tg "sendMessage", {chat_id: чат}` | Универсальный API |
| **Алиасы** |||
| `старт:` | `старт:` | Алиас при старте |
| `команда:` | `команда "/help":` | Алиас при команде |
| **Импорт** |||
| `импорт` | `импорт "file.ccd"` | Подключить файл |
| `импорт пакета` | `импорт "cicada.shop"` | Импорт пакета |
| **Блоки** |||
| `блок` | `блок имя:` | Определить блок |
| `использовать` | `использовать имя` | Вставить блок |
| **Middleware** |||
| `до каждого:` | `до каждого:` | Перед сообщением |
| `после каждого:` | `после каждого:` | После сообщения |
| **Версия** |||
| `версия` | `версия "1.0"` | Версия DSL |
| **Команды меню** |||
| `команды:` | `команды: "/start" - "Запуск"` | Меню Telegram |
| **Глобальные** |||
| `глобально` | `глобально админ = 123` | Общая переменная |
| **Контекст** |||
| `пользователь.` | `пользователь.имя` | Данные пользователя |
| `чат.` | `чат.id` | Данные чата |
| **FSM шаги** |||
| `шаг` | `шаг имя:` | Именованный шаг |
| `вернуть` | `вернуть` | Выйти из шага |
| `повторить шаг` | `повторить шаг` | Повторить текущий |
| `перейти к` | `перейти к шаг имя` | Перейти к шагу |
| **Валидация** |||
| `число()` | `если число(возраст):` | Проверка числа |
| `тип()` | `тип(перем) == "строка"` | Тип переменной |
| **Типы данных** |||
| `пусть` | `пусть x = 100` | Объявление переменной |
| `истина` | `пусть активен = истина` | Boolean true |
| `ложь` | `пусть бан = ложь` | Boolean false |
| `[]` | `пусть товары = ["A", "B"]` | Массив |
| **Шаблоны** |||
| `{}` | `"Привет {имя}!"` | Вставка переменной |

**Режим разработки:** `cicada бот.ccd --debug` — вывод всех сообщений и ошибок

---

## � Обработка ошибок

Cicada предоставляет понятные сообщения об ошибках:

### Типы ошибок

```
❌ SyntaxError: Не понимаю условие: 'если текст = "привет"'
              ^
              Ожидалось: '=='

❌ FileNotFoundError: Импорт не найден: helpers.ccd

❌ RuntimeError: Сценарий 'регистрация' не найден
```

### Отладка

```bash
# Режим разработки с детальным выводом
cicada bot.ccd --debug

# В выводе:
[DEBUG] Загружен файл: bot.ccd
[DEBUG] Версия DSL: 1.0
[DEBUG] Хендлеров: 5
[DEBUG] Сценариев: 2
[DEBUG] ← [123456789] Иван: Привет
[DEBUG] → Ответ: Привет, Иван!
```

### Обработка ошибок в коде

```cicada
при команде "/risky":
    http_get "https://api.example.com/data" → результат
    если тип(результат) == "строка" и содержит(результат, "Ошибка"):
        ответ "⚠️ API недоступен, попробуйте позже"
    иначе:
        ответ "✅ Данные получены"
```

---

## ⚡ Производительность

### Характеристики

| Метрика | Значение |
|---------|----------|
| Пользователей | До 10,000 активных |
| Latency | ~100-300ms |
| Memory | ~50-100MB |
| Storage | JSON (легко мигрируется) |

### Архитектура выполнения

```
User Message
    ↓
Telegram API (webhook/long polling)
    ↓
Parser (tokenize → AST) ~1-2ms
    ↓
Runtime (user context lookup) ~0.1ms
    ↓
Executor (process statement) ~5-20ms
    ↓
Telegram API (send response) ~50-200ms
```

### Оптимизации

- **Memory-based Runtime** — быстрый доступ к контексту пользователя
- **Lazy imports** — модули загружаются только при использовании
- **JSON storage** — простое и быстрое хранилище
- **Block reuse** — блоки кода не дублируются

### Масштабирование

Для высоких нагрузок рекомендуется:

```bash
# Webhook mode (вместо polling)
export CICADA_MODE=webhook
export CICADA_WEBHOOK_URL=https://your-domain.com/webhook

# Redis для состояния (в планах)
export CICADA_STORAGE=redis
export CICADA_REDIS_URL=redis://localhost:6379
```

---

## 🔒 Безопасность

### Встроенная защита

| Угроза | Защита |
|--------|--------|
| **Token leak** | Token в отдельном файле/env |
| **Code injection** | Sandbox execution, нет eval() |
| **Rate limiting** | Автоматическая защита от спама |
| **Input validation** | Валидация всех входных данных |
| **Global state** | Изоляция пользователей |

### Best Practices

```cicada
# Не храните токен в коде
бот getenv("CICADA_TOKEN")  # лучше, чем токен в файле

# Валидация ввода
спросить "Введите сумму:" → сумма
если не число(сумма) или сумма < 0:
    ответ "❌ Некорректная сумма"
    повторить шаг

# Проверка прав
глобально admin_ids = [123456, 789012]
если пользователь.id не в admin_ids:
    ответ "⛔ Нет доступа"
    вернуть

# Логирование действий
лог "Пользователь {пользователь.id} совершил покупку на {сумма}"
```

### Sandbox Execution

- Нет доступа к файловой системе (кроме `db/`)
- Нет сетевых запросов кроме HTTP API
- Нет импорта Python-модулей
- Таймауты на HTTP запросы (30 сек)

---

## �� Архитектура проекта (дерево)

```
cicada/
├── cli.py          # Точка входа (команда cicada)
├── parser.py       # Парсер .ccd → AST
├── executor.py     # Исполнитель AST через Telegram API
├── runner.py       # Загрузчик и оркестратор
├── runtime.py      # Runtime-контекст и память
├── database.py     # JSON-база данных для постоянного хранения
└── adapters/       # Адаптеры API
    └── telegram.py # Telegram Bot API

examples/           # Готовые примеры
    ├── echo.ccd    # Эхо-бот
    ├── shop.ccd    # Магазин
    └── support.ccd # Поддержка

primer.ccd          # Демо-бот
pyproject.toml      # Конфигурация пакета
```

---

## 🤝 Вклад в проект

Баг-репорты, идеи и пул-реквесты приветствуются!

1. Форкните репозиторий
2. Создайте ветку: `git checkout -b feature/amazing-feature`
3. Закоммитьте: `git commit -m 'Add amazing feature'`
4. Пуш: `git push origin feature/amazing-feature`
5. Откройте Pull Request

---

## 📄 Лицензия

Распространяется под лицензией MIT. См. [LICENSE](LICENSE).

---

<p align="center">
  <b>🦋 Пишите ботов на родном языке!</b><br>
  <sub>Cicada — делайте Telegram-ботов просто</sub>
</p>
