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>
This commit is contained in:
161
README.md
Normal file
161
README.md
Normal file
@@ -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
|
||||||
|
```
|
||||||
94
install.bat
94
install.bat
@@ -1,55 +1,95 @@
|
|||||||
@echo off
|
@echo off
|
||||||
setlocal
|
setlocal EnableDelayedExpansion
|
||||||
|
|
||||||
set "INSTALL_DIR=%LOCALAPPDATA%\kisync"
|
set "INSTALL_DIR=%LOCALAPPDATA%\kisync"
|
||||||
set "EXE_NAME=kisync.exe"
|
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.
|
||||||
echo KIS API Builder Sync - Installer
|
echo ==========================================
|
||||||
echo =================================
|
echo kisync - KIS API Builder Sync - Installer
|
||||||
|
echo ==========================================
|
||||||
echo.
|
echo.
|
||||||
|
|
||||||
:: Create install directory
|
:: Create install directory
|
||||||
if not exist "%INSTALL_DIR%" (
|
if not exist "%INSTALL_DIR%" (
|
||||||
mkdir "%INSTALL_DIR%"
|
mkdir "%INSTALL_DIR%"
|
||||||
echo Created: %INSTALL_DIR%
|
echo [+] Created directory: %INSTALL_DIR%
|
||||||
|
) else (
|
||||||
|
echo [=] Directory exists: %INSTALL_DIR%
|
||||||
)
|
)
|
||||||
|
|
||||||
:: Copy exe
|
:: Check if exe is next to this script (offline install)
|
||||||
copy /Y "%~dp0release\%EXE_NAME%" "%INSTALL_DIR%\%EXE_NAME%" >nul 2>&1
|
if exist "%~dp0release\%EXE_NAME%" (
|
||||||
if errorlevel 1 (
|
echo [~] Found local exe, copying...
|
||||||
echo ERROR: Could not copy %EXE_NAME%. Make sure release\kisync.exe exists.
|
copy /Y "%~dp0release\%EXE_NAME%" "%INSTALL_DIR%\%EXE_NAME%" >nul 2>&1
|
||||||
echo Run "npm run package" first to build the exe.
|
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
|
pause
|
||||||
exit /b 1
|
exit /b 1
|
||||||
)
|
)
|
||||||
echo Installed: %INSTALL_DIR%\%EXE_NAME%
|
|
||||||
|
|
||||||
:: Check if already in PATH
|
:: Show version
|
||||||
echo %PATH% | findstr /I /C:"%INSTALL_DIR%" >nul 2>&1
|
echo [+] Installed: %INSTALL_DIR%\%EXE_NAME%
|
||||||
if %errorlevel%==0 (
|
"%INSTALL_DIR%\%EXE_NAME%" --version 2>nul && echo.
|
||||||
echo PATH: already configured
|
|
||||||
goto :done
|
|
||||||
)
|
|
||||||
|
|
||||||
:: Add to user PATH
|
:: Check if already in user PATH
|
||||||
echo Adding to 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"
|
for /f "tokens=2*" %%a in ('reg query "HKCU\Environment" /v Path 2^>nul') do set "USER_PATH=%%b"
|
||||||
|
|
||||||
if defined 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
|
echo !USER_PATH! | findstr /I /C:"%INSTALL_DIR%" >nul 2>&1
|
||||||
) else (
|
if !errorlevel!==0 (
|
||||||
reg add "HKCU\Environment" /v Path /t REG_EXPAND_SZ /d "%INSTALL_DIR%" /f >nul 2>&1
|
set "NEED_PATH=0"
|
||||||
|
echo [=] PATH: already configured
|
||||||
|
)
|
||||||
)
|
)
|
||||||
|
|
||||||
:: Broadcast environment change so new terminals pick it up
|
if !NEED_PATH!==1 (
|
||||||
rundll32.exe user32.dll,UpdatePerIDesktopLayout >nul 2>&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.
|
||||||
echo Done! Open a NEW terminal and run:
|
echo ==========================================
|
||||||
echo kisync --help
|
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.
|
echo.
|
||||||
pause
|
pause
|
||||||
|
|||||||
Reference in New Issue
Block a user