create-entity-app-server 0.0.3 → 0.1.13

package/{src → dist-create/template}/app/schedules/data-retention/config.json

@@ -3,7 +3,5 @@
     "enabled": false,
     "retention_days": 1095,
     "action": "anonymize",
-    "cron": "30 2 * * *",
-    "deploy": true,
-    "minify": false
+    "cron": "30 2 * * *"
 }

package/{src → dist-create/template}/app/schedules/dormancy/config.json

@@ -9,7 +9,5 @@
     "login_url": "",
     "send_completed_email": false,
     "completed_email_subject": "계정이 휴면 처리되었습니다",
-    "completed_email_template": "dormancy_completed",
-    "deploy": true,
-    "minify": false
+    "completed_email_template": "dormancy_completed"
 }

package/{docs → dist-create/template/docs}/scripts-guide.md

@@ -12,9 +12,10 @@
 | [build.sh](#2-buildsh)                   | TypeScript 빌드 + dist/ 패키징        |
 | [push.sh](#3-pushsh)                     | 버전 관리 + Git push                  |
 | [release.sh](#4-releasesh)               | 빌드 + 버전업 + push (원스텝)         |
-| [entity.sh](#5-entitysh)                 | Gateway 전용 엔티티 테이블 생성       |
-| [reset-all.sh](#6-reset-allsh)           | Gateway 전용 엔티티 테이블 초기화     |
-| [gen-table-type.sh](#7-gen-table-typesh) | 엔티티 → Kysely 테이블 타입 자동 생성 |
+| [update-server.sh](#5-update-serversh)   | 최신 gateway 코어 업데이트            |
+| [entity.sh](#6-entitysh)                 | Gateway 전용 엔티티 테이블 생성       |
+| [reset-all.sh](#7-reset-allsh)           | Gateway 전용 엔티티 테이블 초기화     |
+| [gen-table-type.sh](#8-gen-table-typesh) | 엔티티 → Kysely 테이블 타입 자동 생성 |
 
 ---
 
@@ -61,16 +62,24 @@ TypeScript를 컴파일하고 배포용 `dist/`를 패키징합니다.
 ```bash
 ./scripts/build.sh           # 프로덕션 빌드 + dist/ 패키징 + dist.tar.gz 생성
 ./scripts/build.sh --no-tar  # tar.gz 없이 빌드만
+npm run pack:npm             # npm 패키지(.cache/npm-pack/*.tgz) 생성
 ```
 
+`dist.tar.gz`는 서버 배포용 아카이브이고, `npm run pack:npm`으로 만드는 `.tgz`는 `create-entity-app-server` npm 패키지 아카이브입니다.
+
 ### 단계별 동작
 
 | 단계            | 내용                                                                      |
 | --------------- | ------------------------------------------------------------------------- |
-| [1/4] Build     | `npm run build` → TypeScript 컴파일 → `dist/system.js`, `system-api.js`   |
-| [2/4] Package   | `src/app/` 복사, 플러그인 `config.json` ← `config.example.json` 으로 교체 |
-| [3/4] Resources | `configs/`, `entities/`, `templates/`, `scripts/`, `docs/`, `.env` 복사   |
-| [4/4] Archive   | `dist.tar.gz` 생성 (`--no-tar` 시 생략)                                   |
+| [1/5] Build     | `npm run build` → TypeScript 컴파일 → `dist/system.js`, `system-api.js`   |
+| [2/5] Package   | `src/app/` 복사, 플러그인 `config.json` ← `config.example.json` 으로 교체 |
+| [3/5] Resources | `configs/`, `entities/`, `templates/`, `scripts/`, `docs/`, `.env` 복사   |
+| [4/5] Template  | `dist-create/template/` 생성                                              |
+| [5/5] Archive   | `dist.tar.gz` 생성 (`--no-tar` 시 생략)                                   |
+
+- 플러그인 배포용 `config.example.json` 에는 `deploy`, `minify` 를 넣지 않습니다.
+- build 시 플러그인은 `config.example.json` 내용이 그대로 `dist/app/plugins/*/config.json` 으로 복사됩니다.
+- `routes/`, `schedules/` 는 source `config.json` 을 그대로 사용하므로, 배포 산출물에서는 이들만 `deploy`, `minify` 필드를 제거합니다.
 
 ### dist/ 포함 항목
 
@@ -80,8 +89,8 @@ dist/
 ├── system-api.js     — 공개 API 번들 (ok/fail/logger/entityServer 등)
 ├── tsconfig.json     — @gateway/api, @app/* 경로 별칭
 ├── app/              — 사용자 편집 가능한 TypeScript 소스
-│   ├── plugins/      — 플러그인 (config.json = config.example.json 내용)
-│   └── routes/       — 비즈니스 라우트 (config.json 원본 유지)
+│   ├── plugins/      — 플러그인 (config.json = config.example.json 내용, deploy/minify 없음)
+│   └── routes/       — 비즈니스 라우트 (config.json 원본 유지, 배포 시 deploy/minify 제거)
 ├── configs/          — 서버·DB·CORS 설정 파일
 ├── entities/         — 엔티티 스키마 JSON
 ├── templates/        — 확장 템플릿
@@ -94,49 +103,101 @@ dist/
 
 ## 3) push.sh
 
-버전 번호를 올리고 Git push합니다. `package.json`의 `version` 필드를 기준으로 동작합니다.
+버전 번호를 올리고 현재 작업 트리 변경을 함께 commit/push합니다. `package.json`의 `version` 필드를 기준으로 태그를 만듭니다.
 
 ```bash
 ./scripts/push.sh                    # 현재 버전 확인 + 사용법 출력
-./scripts/push.sh version patch      # x.y.Z+1 — 버그 수정
-./scripts/push.sh version minor      # x.Y+1.0 — 기능 추가
-./scripts/push.sh version major      # X+1.0.0 — 호환성 변경
+./scripts/push.sh bump patch         # 로컬 버전만 증가
+./scripts/push.sh version            # 현재 버전 확인
+./scripts/push.sh patch              # x.y.Z+1 — 버그 수정
+./scripts/push.sh minor              # x.Y+1.0 — 기능 추가
+./scripts/push.sh major              # X+1.0.0 — 호환성 변경
+./scripts/push.sh push-current       # 현재 버전 commit + tag + push
 ./scripts/push.sh tag                # 현재 버전으로 git tag만 생성 + push
 ```
 
-### 동작 순서 (version)
+### 동작 순서
 
-1. `package.json` 버전 업
-2. `git add package.json && git commit -m "chore: bump version to vX.Y.Z"`
-3. `git tag gateway-vX.Y.Z`
-4. `git push origin <현재 브랜치>`
-5. `git push origin gateway-vX.Y.Z`
+1. `./scripts/push.sh bump <type>`: `package.json` 버전만 로컬에서 증가
+2. `./scripts/push.sh patch|minor|major`: 버전 증가 + 현재 작업 트리 전체 commit + tag + push + upstream 연결
+3. `./scripts/push.sh push-current`: 현재 버전 기준으로 작업 트리 전체 commit + tag + push
+4. `./scripts/push.sh tag`: 현재 버전으로 태그만 push
 
-> 태그는 `gateway-v` 접두어를 사용합니다 (부모 서버 태그와 구분).
+> 태그는 `v` 접두어를 사용합니다. 예: `v0.1.8`
 
 ---
 
 ## 4) release.sh
 
-빌드 + 버전업 + push를 한 번에 실행합니다.
+GitHub PR 기반으로 `현재 브랜치 -> main -> release` 승격을 진행합니다.
 
 ```bash
-./scripts/release.sh           # patch 릴리즈 (기본값)
-./scripts/release.sh patch     # 버그 수정 릴리즈
-./scripts/release.sh minor     # 기능 추가 릴리즈
-./scripts/release.sh major     # 호환 변경 릴리즈
+./scripts/release.sh           # 사용법 출력
+./scripts/release.sh start     # 현재 브랜치 -> main -> release PR 생성/머지
 ```
 
 ### 동작 순서
 
-1. `build.sh` 실행 (빌드 + 패키징)
-2. `push.sh version <type>` 실행 (버전업 + push)
+1. 현재 브랜치에 커밋 안 된 변경과 push 안 된 커밋이 없는지 검사
+2. 현재 브랜치가 `main` 이 아니면 `현재 브랜치 -> main` PR 생성/머지
+3. `main -> release` PR 생성/머지
+4. `release` 브랜치 push 이벤트에서 GitHub Actions 가 `v<version>` 태그 생성
+5. 태그 push 이벤트에서 GitHub Actions 가 GitHub Release 생성
+6. 같은 태그 이벤트에서 `build.sh` 실행 후 npm publish 수행
+
+> 실제 릴리즈는 `./scripts/release.sh start` 로 실행합니다. `./scripts/release.sh` 는 사용법만 출력합니다.
+
+### 사전 조건
+
+- `./scripts/build.sh` 로 빌드 검증이 끝나 있어야 합니다.
+- `./scripts/push.sh` 로 현재 브랜치 변경 사항이 원격에 push 되어 있어야 합니다. 이 스크립트는 origin/<현재브랜치> upstream 도 함께 연결합니다.
+- `gh auth status` 가 정상이어야 합니다.
+- GitHub 저장소에 `release` 브랜치가 있어야 합니다.
+- GitHub Secrets 에 `NPM_TOKEN` 이 설정되어 있어야 태그 생성 후 npm publish 가 성공합니다.
+
+> GitHub Releases 페이지에 버전이 보이려면 태그만으로는 부족하고, 태그 push 시 GitHub Release 객체도 생성되어야 합니다. 현재 워크플로는 이 단계까지 자동 처리합니다.
+
+> `release.sh` 는 로컬 커밋, Git push, npm publish 를 직접 하지 않습니다. 릴리즈 승격만 담당합니다.
+
+---
+
+## 5) update-server.sh
+
+생성된 Gateway 프로젝트의 코어 파일을 최신 npm 패키지 버전으로 업데이트합니다.
+
+```bash
+./scripts/update-server.sh version      # 현재 코어 버전 + 최신 버전 확인
+./scripts/update-server.sh latest       # 최신 버전으로 업데이트
+./scripts/update-server.sh 0.0.8        # 특정 버전으로 업데이트
+```
+
+### 동작
+
+1. npm registry 에서 `create-entity-app-server` 최신 버전을 조회
+2. 해당 패키지 tarball 을 내려받아 `dist-create/template/` 기준으로 코어 파일 추출
+3. 아래 항목만 업데이트
+
+- `system.js`
+- `system-api.js`
+- `scripts/run.sh`, `scripts/entity.sh`, `scripts/reset-all.sh`, `scripts/update-server.sh`
+- `docs/`
+- `tsconfig.json`
+- `.env.example`
+- `.gateway-version`
+- `package.json`의 `scripts`, `dependencies`, `optionalDependencies`, `devDependencies`, `engines`, `os`, `cpu`
+
+### 보존 대상
+
+- `app/`
+- `configs/`
+- `.env`
+- `package.json`의 `name`, `version`, `private` 등 앱 고유 메타데이터
 
-> 빠른 배포 사이클에서 사용합니다. 빌드와 push를 개별적으로 제어하려면 `build.sh` → `push.sh`를 따로 실행하세요.
+> 업데이트 후에는 `npm install` 이 자동 실행됩니다.
 
 ---
 
-## 5) entity.sh
+## 6) entity.sh
 
 `entities/` 폴더의 JSON 스키마를 entity-server에 등록(테이블 생성)합니다.
 
@@ -175,7 +236,7 @@ dist/
 
 ---
 
-## 6) reset-all.sh
+## 7) reset-all.sh
 
 Gateway 전용 엔티티 테이블을 **드롭 후 재생성**합니다.
 
@@ -205,6 +266,16 @@ Gateway 전용 엔티티 테이블을 **드롭 후 재생성**합니다.
 
 ---
 
+## 8) gen-table-type.sh
+
+엔티티 JSON을 기준으로 Kysely 타입 정의를 생성합니다.
+
+```bash
+./scripts/gen-table-type.sh
+```
+
+---
+
 ## 자주 쓰는 워크플로
 
 ### 첫 설치 후 초기화

package/dist-create/template/scripts/update-server.sh

@@ -0,0 +1,391 @@
+#!/bin/bash
+# update-server.sh — Entity App Server 코어 업데이트
+#
+# 사용법:
+#   ./scripts/update-server.sh             # 도움말
+#   ./scripts/update-server.sh version     # 현재 코어 버전 + 최신 태그 확인
+#   ./scripts/update-server.sh latest      # 최신 태그로 업데이트
+#   ./scripts/update-server.sh 0.0.8       # 특정 버전으로 업데이트
+#   ./scripts/update-server.sh v0.0.8
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+PACKAGE_NAME="create-entity-app-server"
+VERSION_FILE="$PROJECT_ROOT/.gateway-version"
+PID_FILE="$PROJECT_ROOT/.gateway.pid"
+MANAGED_SCRIPTS=("run.sh" "entity.sh" "reset-all.sh" "update-server.sh")
+MANAGED_FILES=("system.js" "system-api.js" "tsconfig.json" ".env.example" ".gateway-version")
+
+cd "$PROJECT_ROOT"
+
+if [ ! -f "$PROJECT_ROOT/system.js" ]; then
+    echo "❌ 이 스크립트는 create-entity-app-server 로 생성된 프로젝트 루트에서 실행해야 합니다."
+    echo "   현재 위치: $PROJECT_ROOT"
+    exit 1
+fi
+
+trim() {
+    echo "$1" | tr -d '[:space:]'
+}
+
+normalize_version() {
+    local raw="$1"
+    raw="${raw#gateway-v}"
+    raw="${raw#v}"
+    echo "$raw"
+}
+
+is_semver() {
+    [[ "$1" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]
+}
+
+compare_versions() {
+    local left="$1"
+    local right="$2"
+
+    if [ "$left" = "$right" ]; then
+        echo 0
+        return
+    fi
+
+    local smallest
+    smallest=$(printf '%s\n%s\n' "$left" "$right" | sort -V | head -n 1)
+    if [ "$smallest" = "$left" ]; then
+        echo -1
+    else
+        echo 1
+    fi
+}
+
+current_gateway_version() {
+    if [ -f "$VERSION_FILE" ]; then
+        local value
+        value=$(trim "$(cat "$VERSION_FILE" 2>/dev/null || true)")
+        value=$(normalize_version "$value")
+        if [[ "$value" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "$value"
+            return
+        fi
+    fi
+    echo "(알 수 없음)"
+}
+
+fetch_text() {
+    local url="$1"
+    if command -v curl >/dev/null 2>&1; then
+        curl -fsSL "$url"
+    elif command -v wget >/dev/null 2>&1; then
+        wget -qO- "$url"
+    else
+        echo "❌ curl 또는 wget 이 필요합니다." >&2
+        exit 1
+    fi
+}
+
+download_file() {
+    local url="$1"
+    local dest="$2"
+    local tmp="${dest}.tmp"
+
+    if command -v curl >/dev/null 2>&1; then
+        curl -fsSL --retry 3 -o "$tmp" "$url"
+    elif command -v wget >/dev/null 2>&1; then
+        wget -q -O "$tmp" "$url"
+    else
+        echo "❌ curl 또는 wget 이 필요합니다." >&2
+        exit 1
+    fi
+
+    mv "$tmp" "$dest"
+}
+
+latest_gateway_version() {
+    local latest
+    latest=$(fetch_text "https://registry.npmjs.org/${PACKAGE_NAME}/latest" | node -e 'const fs = require("fs"); const data = JSON.parse(fs.readFileSync(0, "utf8")); process.stdout.write(data.version || "");')
+
+    if [ -z "$latest" ]; then
+        echo "❌ 최신 패키지 버전을 가져오지 못했습니다." >&2
+        exit 1
+    fi
+
+    echo "$latest"
+}
+
+package_tarball_url() {
+    local version="$1"
+    local tarball
+    tarball=$(fetch_text "https://registry.npmjs.org/${PACKAGE_NAME}/${version}" | node -e 'const fs = require("fs"); const data = JSON.parse(fs.readFileSync(0, "utf8")); process.stdout.write(data.dist?.tarball || "");')
+
+    if [ -z "$tarball" ]; then
+        echo "❌ ${PACKAGE_NAME}@${version} 패키지 tarball URL을 찾지 못했습니다." >&2
+        exit 1
+    fi
+
+    echo "$tarball"
+}
+
+get_gateway_port() {
+    local config_port
+    local env_port=""
+
+    if [ -f ".env" ]; then
+        env_port=$(grep '^SERVER_PORT=' .env | tail -n 1 | cut -d '=' -f2-)
+        if [ -z "$env_port" ]; then
+            env_port=$(grep '^PORT=' .env | tail -n 1 | cut -d '=' -f2-)
+        fi
+    fi
+
+    env_port=$(trim "$env_port")
+    if [[ "$env_port" =~ ^[0-9]+$ ]] && [ "$env_port" -gt 0 ]; then
+        echo "$env_port"
+        return
+    fi
+
+    if [ -f "$PROJECT_ROOT/configs/server.json" ]; then
+        config_port=$(grep -E '"port"[[:space:]]*:' "$PROJECT_ROOT/configs/server.json" | head -n 1 | sed -E 's/.*:[[:space:]]*([0-9]+).*/\1/')
+        config_port=$(trim "$config_port")
+        if [[ "$config_port" =~ ^[0-9]+$ ]] && [ "$config_port" -gt 0 ]; then
+            echo "$config_port"
+            return
+        fi
+    fi
+
+    echo "3000"
+}
+
+find_running_pids() {
+    local pid_list=()
+
+    if [ -f "$PID_FILE" ]; then
+        local pid
+        pid=$(trim "$(cat "$PID_FILE" 2>/dev/null || true)")
+        if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+            pid_list+=("$pid")
+        fi
+    fi
+
+    local port
+    port=$(get_gateway_port)
+    while IFS= read -r pid; do
+        [ -n "$pid" ] && pid_list+=("$pid")
+    done < <(ss -ltnp 2>/dev/null | sed -n "s/.*:${port} .*pid=\([0-9]\+\).*/\1/p" | sort -u)
+
+    printf '%s\n' "${pid_list[@]}" | awk 'NF && !seen[$0]++'
+}
+
+ensure_gateway_stopped() {
+    mapfile -t running_pids < <(find_running_pids)
+    if [ "${#running_pids[@]}" -eq 0 ]; then
+        return 0
+    fi
+
+    echo ""
+    echo "⚠️  현재 Entity App Server가 실행 중입니다."
+    ps -p "${running_pids[0]}" -o pid,etime,cmd --no-headers 2>/dev/null || true
+    echo ""
+    read -r -p "업데이트를 위해 서버를 중지할까요? [y/N]: " input
+    input=$(echo "$input" | tr '[:upper:]' '[:lower:]')
+
+    if [ "$input" != "y" ] && [ "$input" != "yes" ]; then
+        echo "❌ 업데이트를 취소했습니다."
+        exit 1
+    fi
+
+    if [ -x "$PROJECT_ROOT/scripts/run.sh" ]; then
+        "$PROJECT_ROOT/scripts/run.sh" stop || true
+    else
+        for pid in "${running_pids[@]}"; do
+            kill "$pid" 2>/dev/null || true
+        done
+    fi
+
+    sleep 0.2
+    mapfile -t running_pids < <(find_running_pids)
+    if [ "${#running_pids[@]}" -gt 0 ]; then
+        echo "❌ 서버 중지에 실패했습니다. 업데이트를 중단합니다."
+        exit 1
+    fi
+
+    rm -f "$PID_FILE"
+    echo "✅ 서버 중지 완료"
+}
+
+sync_package_json() {
+    local upstream_pkg="$1"
+    local target_pkg="$PROJECT_ROOT/package.json"
+
+    [ -f "$target_pkg" ] || return 0
+    [ -f "$upstream_pkg" ] || return 0
+
+    node - "$target_pkg" "$upstream_pkg" <<'NODE'
+const fs = require("fs");
+
+const [targetPath, upstreamPath] = process.argv.slice(2);
+const target = JSON.parse(fs.readFileSync(targetPath, "utf8"));
+const upstream = JSON.parse(fs.readFileSync(upstreamPath, "utf8"));
+
+const preserved = [
+  "name",
+  "version",
+  "private",
+  "description",
+  "keywords",
+  "author",
+  "license",
+  "repository",
+  "bugs",
+  "homepage"
+];
+
+const synced = [
+  "type",
+  "scripts",
+  "dependencies",
+  "optionalDependencies",
+  "devDependencies",
+  "engines",
+  "os",
+  "cpu"
+];
+
+const next = { ...target };
+
+for (const key of synced) {
+  if (Object.prototype.hasOwnProperty.call(upstream, key)) {
+    next[key] = upstream[key];
+  }
+}
+
+for (const key of preserved) {
+  if (Object.prototype.hasOwnProperty.call(target, key)) {
+    next[key] = target[key];
+  }
+}
+
+fs.writeFileSync(targetPath, `${JSON.stringify(next, null, 2)}\n`);
+NODE
+}
+
+install_version() {
+    local target_ver
+    target_ver=$(normalize_version "$1")
+    local current_ver
+    current_ver=$(current_gateway_version)
+
+    ensure_gateway_stopped
+
+    local url
+    url=$(package_tarball_url "$target_ver")
+    local tmp_tar="/tmp/entity-app-server-${target_ver}.tar.gz"
+    local tmp_dir="/tmp/entity-app-server-${target_ver}"
+
+    echo ""
+    echo "📦 ${PACKAGE_NAME}@${target_ver} 다운로드 중..."
+    download_file "$url" "$tmp_tar"
+
+    rm -rf "$tmp_dir"
+    mkdir -p "$tmp_dir"
+    tar -xzf "$tmp_tar" -C "$tmp_dir"
+
+    local src_root
+    src_root=$(find "$tmp_dir" -mindepth 1 -maxdepth 1 -type d | head -n 1)
+    if [ -z "$src_root" ]; then
+        echo "❌ 다운로드한 아카이브를 해제하지 못했습니다."
+        rm -rf "$tmp_dir" "$tmp_tar"
+        exit 1
+    fi
+
+    local template_root="$src_root/dist-create/template"
+    if [ ! -d "$template_root" ]; then
+        echo "❌ ${PACKAGE_NAME}@${target_ver} 패키지에 dist-create/template 이 없습니다."
+        rm -rf "$tmp_dir" "$tmp_tar"
+        exit 1
+    fi
+
+    echo ""
+    echo "  코어 파일 동기화:"
+    for file in "${MANAGED_FILES[@]}"; do
+        if [ -e "$template_root/$file" ]; then
+            cp -R "$template_root/$file" "$PROJECT_ROOT/$file"
+            printf '    ✔ %s\n' "$file"
+        fi
+    done
+
+    mkdir -p "$PROJECT_ROOT/scripts"
+    for script in "${MANAGED_SCRIPTS[@]}"; do
+        if [ -f "$template_root/scripts/$script" ]; then
+            cp "$template_root/scripts/$script" "$PROJECT_ROOT/scripts/$script"
+            chmod +x "$PROJECT_ROOT/scripts/$script"
+            printf '    ✔ scripts/%s\n' "$script"
+        fi
+    done
+
+    if [ -d "$template_root/docs" ]; then
+        mkdir -p "$PROJECT_ROOT/docs"
+        cp -R "$template_root/docs/." "$PROJECT_ROOT/docs/"
+        echo "    ✔ docs/"
+    fi
+
+    sync_package_json "$src_root/package.json"
+    if [ -f "$PROJECT_ROOT/package.json" ]; then
+        echo ""
+        echo "  npm install 실행 중..."
+        npm install
+    fi
+
+    rm -rf "$tmp_dir" "$tmp_tar"
+
+    echo ""
+    echo "✅ 업데이트 완료: v${current_ver} → v${target_ver}"
+    echo "   필요하면 다시 실행: ./scripts/run.sh dev"
+}
+
+ARG="${1:-}"
+
+case "$ARG" in
+    "")
+        echo "update-server.sh — Entity App Server 코어 업데이트"
+        echo ""
+        echo "사용법:"
+        echo "  ./scripts/update-server.sh version"
+        echo "  ./scripts/update-server.sh latest"
+        echo "  ./scripts/update-server.sh <버전>"
+        echo ""
+        echo "업데이트 대상: system.js / system-api.js / scripts / docs / tsconfig.json / .env.example / package.json(deps)"
+        echo "보존 대상: app/ / configs/ / .env / package.json의 name/version/private"
+        ;;
+
+    "version")
+        echo "🔍 버전 확인 중..."
+        CURRENT="$(current_gateway_version)"
+        LATEST="$(latest_gateway_version)"
+        echo ""
+        echo "  현재 코어 버전: v${CURRENT}"
+        echo "  최신 패키지 버전: v${LATEST}"
+        echo ""
+        if [ "$CURRENT" = "$LATEST" ]; then
+            echo "✅ 최신 버전입니다."
+        elif is_semver "$CURRENT" && [ "$(compare_versions "$CURRENT" "$LATEST")" = "1" ]; then
+            echo "ℹ️  현재 코어가 npm 최신 버전보다 더 새롭습니다."
+        else
+            echo "💡 업데이트 가능: ./scripts/update-server.sh latest"
+        fi
+        ;;
+
+    "latest")
+        echo "🔍 최신 버전 확인 중..."
+        CURRENT="$(current_gateway_version)"
+        LATEST="$(latest_gateway_version)"
+        if is_semver "$CURRENT" && [ "$(compare_versions "$CURRENT" "$LATEST")" = "1" ]; then
+            echo "ℹ️  현재 코어(v${CURRENT})가 npm 최신 버전(v${LATEST})보다 더 새롭습니다. 다운그레이드하지 않습니다."
+            exit 0
+        fi
+        install_version "$LATEST"
+        ;;
+
+    *)
+        install_version "$ARG"
+        ;;
+esac