Add self-downloading installer and README

- install.bat downloads exe from Gitea release or uses local copy - Adds to user PATH automatically - README with full usage guide, file structure, conflict resolution Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-14 16:36:09 +03:00
parent f899eeb4ef
commit 302c7ab9f5
2 changed files with 228 additions and 27 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,161 @@
+# 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
+```
--- a/install.bat
+++ b/install.bat
@@ -1,55 +1,95 @@
@echo off
-setlocal
+setlocal EnableDelayedExpansion

 set "INSTALL_DIR=%LOCALAPPDATA%\kisync"
 set "EXE_NAME=kisync.exe"
+set "DOWNLOAD_URL=https://gitea.esh-service.ru/public/api_builder_cli_client/releases/download/v1.0.0/kisync.exe"

 echo.
-echo  KIS API Builder Sync - Installer
-echo  =================================
+echo  ==========================================
+echo   kisync - KIS API Builder Sync - Installer
+echo  ==========================================
 echo.

 :: Create install directory
 if not exist "%INSTALL_DIR%" (
    mkdir "%INSTALL_DIR%"
-    echo  Created: %INSTALL_DIR%
+    echo  [+] Created directory: %INSTALL_DIR%
+) else (
+    echo  [=] Directory exists:  %INSTALL_DIR%
 )

-:: Copy exe
-copy /Y "%~dp0release\%EXE_NAME%" "%INSTALL_DIR%\%EXE_NAME%" >nul 2>&1
-if errorlevel 1 (
-    echo  ERROR: Could not copy %EXE_NAME%. Make sure release\kisync.exe exists.
-    echo  Run "npm run package" first to build the exe.
+:: Check if exe is next to this script (offline install)
+if exist "%~dp0release\%EXE_NAME%" (
+    echo  [~] Found local exe, copying...
+    copy /Y "%~dp0release\%EXE_NAME%" "%INSTALL_DIR%\%EXE_NAME%" >nul 2>&1
+    goto :check_copy
+)
+if exist "%~dp0%EXE_NAME%" (
+    echo  [~] Found local exe, copying...
+    copy /Y "%~dp0%EXE_NAME%" "%INSTALL_DIR%\%EXE_NAME%" >nul 2>&1
+    goto :check_copy
+)
+
+:: Download from Gitea
+echo  [~] Downloading kisync.exe ...
+echo      %DOWNLOAD_URL%
+echo.
+powershell -Command "[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12; (New-Object Net.WebClient).DownloadFile('%DOWNLOAD_URL%', '%INSTALL_DIR%\%EXE_NAME%')" 2>nul
+
+:check_copy
+if not exist "%INSTALL_DIR%\%EXE_NAME%" (
+    echo.
+    echo  [!] ERROR: Failed to get kisync.exe
+    echo      Try downloading manually from:
+    echo      %DOWNLOAD_URL%
+    echo      and place it in: %INSTALL_DIR%\
+    echo.
    pause
    exit /b 1
 )
-echo  Installed: %INSTALL_DIR%\%EXE_NAME%

-:: Check if already in PATH
-echo %PATH% | findstr /I /C:"%INSTALL_DIR%" >nul 2>&1
-if %errorlevel%==0 (
-    echo  PATH: already configured
-    goto :done
-)
+:: Show version
+echo  [+] Installed: %INSTALL_DIR%\%EXE_NAME%
+"%INSTALL_DIR%\%EXE_NAME%" --version 2>nul && echo.

-:: Add to user PATH
-echo  Adding to user PATH...
+:: Check if already in user PATH
+set "NEED_PATH=1"
 for /f "tokens=2*" %%a in ('reg query "HKCU\Environment" /v Path 2^>nul') do set "USER_PATH=%%b"

 if defined USER_PATH (
-    reg add "HKCU\Environment" /v Path /t REG_EXPAND_SZ /d "%USER_PATH%;%INSTALL_DIR%" /f >nul 2>&1
-) else (
-    reg add "HKCU\Environment" /v Path /t REG_EXPAND_SZ /d "%INSTALL_DIR%" /f >nul 2>&1
+    echo !USER_PATH! | findstr /I /C:"%INSTALL_DIR%" >nul 2>&1
+    if !errorlevel!==0 (
+        set "NEED_PATH=0"
+        echo  [=] PATH: already configured
+    )
 )

-:: Broadcast environment change so new terminals pick it up
-rundll32.exe user32.dll,UpdatePerIDesktopLayout >nul 2>&1
+if !NEED_PATH!==1 (
+    echo  [~] Adding to user PATH...
+    if defined USER_PATH (
+        reg add "HKCU\Environment" /v Path /t REG_EXPAND_SZ /d "%USER_PATH%;%INSTALL_DIR%" /f >nul 2>&1
+    ) else (
+        reg add "HKCU\Environment" /v Path /t REG_EXPAND_SZ /d "%INSTALL_DIR%" /f >nul 2>&1
+    )

-echo  PATH: added %INSTALL_DIR%
+    :: Notify system about environment change
+    powershell -Command "[Environment]::SetEnvironmentVariable('_kisync_refresh','1','User'); [Environment]::SetEnvironmentVariable('_kisync_refresh', $null, 'User')" 2>nul
+
+    echo  [+] PATH: added %INSTALL_DIR%
+)

-:done
 echo.
-echo  Done! Open a NEW terminal and run:
+echo  ==========================================
+echo   Installation complete!
+echo  ==========================================
+echo.
+echo   Open a NEW terminal and run:
 echo     kisync --help
 echo.
+echo   Quick start:
+echo     cd my-project
+echo     kisync init
+echo     kisync pull
+echo.
 pause