# kisync — KIS API Builder Sync CLI

CLI-клиент для двусторонней синхронизации локальных файлов с сервером [KIS API Builder](https://gitea.esh-service.ru/public/api_builder_cli_client).

## Установка

### Вариант 1: Автоматическая (Windows)

Скачать и запустить [`install.bat`](https://gitea.esh-service.ru/public/api_builder_cli_client/releases/download/v1.0.0/install.bat) — он сам скачает `kisync.exe`, установит в `%LOCALAPPDATA%\kisync\` и добавит в PATH.

### Вариант 2: Ручная

1. Скачать `kisync.exe` со [страницы релиза](https://gitea.esh-service.ru/public/api_builder_cli_client/releases/tag/v1.0.0)
2. Положить в любую папку, которая есть в PATH (например `C:\Users\<user>\AppData\Local\kisync\`)
3. Проверить: `kisync --help`

---

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

```bash
# 1. Создать папку проекта
mkdir my-api-endpoints
cd my-api-endpoints

# 2. Подключиться к серверу API Builder
kisync init
#   Server URL: http://your-server:3000
#   Username: admin
#   Password: ****

# 3. Скачать все эндпоинты с сервера
kisync pull

# 4. Редактировать файлы (запросы, скрипты)
#    ... правишь query.sql, main.js, request.http ...

# 5. Проверить что изменилось
kisync status

# 6. Отправить изменения на сервер
kisync push
```

---

## Команды

| Команда | Описание |
|---------|----------|
| `kisync init` | Подключиться к серверу (ввести URL, логин, пароль) |
| `kisync pull` | Скачать эндпоинты с сервера в локальные файлы |
| `kisync pull --force` | Перезаписать локальные изменения версией с сервера |
| `kisync push` | Загрузить локальные изменения на сервер |
| `kisync push --force` | Принудительно перезаписать сервер, игнорируя конфликты |
| `kisync status` | Показать что изменилось локально и на сервере |

---

## Структура файлов

После `kisync pull` в папке появится такая структура:

```
my-api-endpoints/
├── .kisync.json              # Конфиг (host, token) — НЕ коммитить!
├── .kisync-state.json        # Состояние синхронизации — НЕ коммитить!
│
├── Пользователи/             # Папка (Folder в API Builder)
│   ├── _folder.json          # Метаданные папки
│   │
│   ├── Получить список/      # Эндпоинт (SQL)
│   │   ├── endpoint.json     # Настройки: method, path, parameters...
│   │   └── query.sql         # SQL-запрос
│   │
│   ├── Создать/              # Эндпоинт (Script)
│   │   ├── endpoint.json
│   │   ├── main.js           # JavaScript код (или main.py)
│   │   └── queries/          # Запросы, используемые в скрипте
│   │       ├── _index.json   # Индекс запросов (имена, БД)
│   │       ├── insert.sql    # SQL-запрос
│   │       └── notify.http   # HTTP-запрос (AQL)
│   │
│   └── Внешний сервис/       # Эндпоинт (AQL / HTTP)
│       ├── endpoint.json
│       └── request.http      # HTTP-запрос
│
└── _no_folder/               # Эндпоинты без папки
    └── ...
```

### Файлы по типу эндпоинта

| Тип | Файлы |
|-----|-------|
| **SQL** | `endpoint.json` + `query.sql` |
| **Script** | `endpoint.json` + `main.js`/`main.py` + `queries/*.sql` |
| **AQL (HTTP)** | `endpoint.json` + `request.http` |

### Формат `request.http`

```http
POST /api/v1/patients
Content-Type: application/json

{
  "name": "{{name}}",
  "age": {{age}}
}
```

---

## Конфликты

При `push` и `pull` kisync проверяет, не менял ли кто-то эндпоинт на сервере с момента последней синхронизации.

```
$ kisync push

  ! CONFLICT:  Пользователи/Создать
               server updated: 14.03.2026, 15:42:31
               your base:      14.03.2026, 12:00:00

Use "kisync push --force" to overwrite server changes.
Or run "kisync pull --force" to get the latest version first.
```

**Варианты решения:**
- `kisync push --force` — перезаписать сервер своей версией
- `kisync pull --force` — забрать серверную версию (потерять свои правки)
- Сделать копию своих файлов, `pull --force`, вручную смержить

---

## Работа в команде с Git

Можно хранить эндпоинты в Git-репозитории. Добавьте в `.gitignore`:

```
.kisync.json
.kisync-state.json
```

Workflow:
1. `kisync pull` — скачать с сервера
2. `git commit` — зафиксировать
3. Редактировать файлы
4. `kisync push` — отправить на сервер
5. `git commit` — зафиксировать изменения

---

## Сборка из исходников

```bash
git clone ssh://git@gitea.esh-service.ru:2222/public/api_builder_cli_client.git
cd api_builder_cli_client
npm install
npm run package    # → release/kisync.exe
```