diff --git a/README.md b/README.md new file mode 100644 index 0000000..bd6be60 --- /dev/null +++ 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\\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 +``` diff --git a/install.bat b/install.bat index 7707851..1cec7fd 100644 --- 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 kisync --help +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