create-entity-server 0.0.9 → 0.0.23

package/template/scripts/run.sh

@@ -11,6 +11,10 @@ DATABASE_CONFIG="$PROJECT_ROOT/configs/database.json"
 RUN_DIR="$PROJECT_ROOT/.run"
 PID_FILE="$RUN_DIR/entity-server.pid"
 STDOUT_LOG="$PROJECT_ROOT/logs/server.out.log"
+SERVER_BIN="$PROJECT_ROOT/bin/entity-server"
+if [ ! -f "$SERVER_BIN" ] && [ -f "$PROJECT_ROOT/entity-server" ]; then
+    SERVER_BIN="$PROJECT_ROOT/entity-server"
+fi
 
 mkdir -p "$RUN_DIR" "$PROJECT_ROOT/logs"
 
@@ -25,6 +29,22 @@ get_server_value() {
     local fallback="$2"
     local value
 
+    if [ "$key" = "port" ]; then
+        local env_port
+        env_port="${SERVER_PORT:-${PORT:-}}"
+        if [ -z "$env_port" ] && [ -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=$(echo "$env_port" | tr -d '[:space:]')
+        if [[ "$env_port" =~ ^[0-9]+$ ]] && [ "$env_port" -gt 0 ]; then
+            echo "$env_port"
+            return
+        fi
+    fi
+
     value=$(grep -E "\"$key\"[[:space:]]*:" "$SERVER_CONFIG" | head -n 1 | sed -E 's/.*:[[:space:]]*"?([^",}]+)"?.*/\1/')
     value=$(echo "$value" | tr -d '[:space:]')
     if [ -z "$value" ]; then
@@ -35,60 +55,61 @@ get_server_value() {
 }
 
 is_running() {
+    local port_pid
+    port_pid=$(find_pid_by_port)
+
     if [ ! -f "$PID_FILE" ]; then
+        if [ -n "$port_pid" ] && kill -0 "$port_pid" 2>/dev/null; then
+            return 0
+        fi
         return 1
     fi
     local pid
     pid=$(cat "$PID_FILE" 2>/dev/null)
     if [ -z "$pid" ]; then
+        if [ -n "$port_pid" ] && kill -0 "$port_pid" 2>/dev/null; then
+            return 0
+        fi
         return 1
     fi
-    kill -0 "$pid" 2>/dev/null
-}
-
-stop_server() {
-    if [ ! -f "$PID_FILE" ]; then
-        if [ "$LANGUAGE" = "en" ]; then
-            echo "ℹ️  Server is not running (pid file not found)."
-        else
-            echo "ℹ️  서버가 실행 중이 아닙니다 (pid 파일 없음)."
-        fi
+    if kill -0 "$pid" 2>/dev/null; then
         return 0
     fi
 
-    local pid
-    pid=$(cat "$PID_FILE" 2>/dev/null)
-    if [ -z "$pid" ]; then
-        rm -f "$PID_FILE"
-        if [ "$LANGUAGE" = "en" ]; then
-            echo "ℹ️  Empty pid file removed."
-        else
-            echo "ℹ️  비어있는 pid 파일을 정리했습니다."
-        fi
+    if [ -n "$port_pid" ] && kill -0 "$port_pid" 2>/dev/null; then
         return 0
     fi
 
+    return 1
+}
+
+find_pid_by_port() {
+    local port
+    port=$(get_server_value "port" "3400")
+    ss -ltnp 2>/dev/null | grep ":$port " | sed -n 's/.*pid=\([0-9]\+\).*/\1/p' | head -n 1
+}
+
+stop_pid_with_confirm() {
+    local pid="$1"
+    local reason="$2"
+
+    if [ -z "$pid" ]; then
+        return 1
+    fi
     if ! kill -0 "$pid" 2>/dev/null; then
-        rm -f "$PID_FILE"
-        if [ "$LANGUAGE" = "en" ]; then
-            echo "ℹ️  Stale pid file removed (process not found)."
-        else
-            echo "ℹ️  실행 중인 프로세스가 없어 stale pid 파일을 정리했습니다."
-        fi
-        return 0
+        return 1
     fi
 
-    # 실행 중인 프로세스 정보 표시 후 확인
     local proc_info
     proc_info=$(ps -p "$pid" -o pid,user,etime,args --no-headers 2>/dev/null | head -1)
     if [ "$LANGUAGE" = "en" ]; then
-        echo "Running process:"
+        echo "Running process ($reason):"
         echo "  PID   USER     ELAPSED  COMMAND"
         echo "  $proc_info"
         echo ""
         read -r -p "Stop this process? [y/N]: " input
     else
-        echo "실행 중인 프로세스:"
+        echo "실행 중인 프로세스($reason):"
         echo "  PID   USER     실행시간  COMMAND"
         echo "  $proc_info"
         echo ""
@@ -128,16 +149,78 @@ stop_server() {
     return 0
 }
 
+stop_server() {
+    if [ ! -f "$PID_FILE" ]; then
+        local port_pid
+        port_pid=$(find_pid_by_port)
+        if [ -n "$port_pid" ]; then
+            stop_pid_with_confirm "$port_pid" "port fallback"
+            return $?
+        fi
+        if [ "$LANGUAGE" = "en" ]; then
+            echo "ℹ️  Server is not running (pid file not found)."
+        else
+            echo "ℹ️  서버가 실행 중이 아닙니다 (pid 파일 없음)."
+        fi
+        return 0
+    fi
+
+    local pid
+    pid=$(cat "$PID_FILE" 2>/dev/null)
+    if [ -z "$pid" ]; then
+        rm -f "$PID_FILE"
+        local port_pid
+        port_pid=$(find_pid_by_port)
+        if [ -n "$port_pid" ]; then
+            stop_pid_with_confirm "$port_pid" "port fallback"
+            return $?
+        fi
+        if [ "$LANGUAGE" = "en" ]; then
+            echo "ℹ️  Empty pid file removed."
+        else
+            echo "ℹ️  비어있는 pid 파일을 정리했습니다."
+        fi
+        return 0
+    fi
+
+    if ! kill -0 "$pid" 2>/dev/null; then
+        rm -f "$PID_FILE"
+        local port_pid
+        port_pid=$(find_pid_by_port)
+        if [ -n "$port_pid" ]; then
+            stop_pid_with_confirm "$port_pid" "port fallback"
+            return $?
+        fi
+        if [ "$LANGUAGE" = "en" ]; then
+            echo "ℹ️  Stale pid file removed (process not found)."
+        else
+            echo "ℹ️  실행 중인 프로세스가 없어 stale pid 파일을 정리했습니다."
+        fi
+        return 0
+    fi
+
+    stop_pid_with_confirm "$pid" "pid file"
+    return $?
+}
+
 show_status() {
     if is_running; then
-        ./bin/entity-server banner-status RUNNING
+		local status_pid
+		status_pid=$(find_pid_by_port)
+        "$SERVER_BIN" banner-status RUNNING
         if [ "$LANGUAGE" = "en" ]; then
+			if [ -n "$status_pid" ]; then
+				echo "PID: $status_pid (detected by port)"
+			fi
             echo "Stop: ./run.sh stop"
         else
+			if [ -n "$status_pid" ]; then
+				echo "PID: $status_pid (포트 기준 감지)"
+			fi
             echo "중지: ./run.sh stop"
         fi
     else
-        ./bin/entity-server banner-status STOPPED
+        "$SERVER_BIN" banner-status STOPPED
         if [ "$LANGUAGE" = "en" ]; then
             echo "Start: ./run.sh start"
         else
@@ -210,11 +293,11 @@ if [ ! -f "$DATABASE_CONFIG" ]; then
     exit 1
 fi
 
-if [ ! -f bin/entity-server ]; then
+if [ ! -f "$SERVER_BIN" ]; then
     if [ "$LANGUAGE" = "en" ]; then
-        echo "❌ bin/entity-server not found"
+        echo "❌ entity-server binary not found (bin/entity-server or ./entity-server)"
     else
-        echo "❌ bin/entity-server 파일이 없습니다"
+        echo "❌ entity-server 바이너리 파일이 없습니다 (bin/entity-server 또는 ./entity-server)"
     fi
     exit 1
 fi
@@ -241,7 +324,7 @@ case "$MODE" in
 
         sed -E -i 's/("environment"[[:space:]]*:[[:space:]]*")[^"]+(")/\1development\2/' "$SERVER_CONFIG"
         sed -E -i 's/("default"[[:space:]]*:[[:space:]]*")[^"]+(")/\1development\2/' "$DATABASE_CONFIG"
-        ./bin/entity-server
+        "$SERVER_BIN"
         ;;
         
     start)
@@ -266,8 +349,8 @@ case "$MODE" in
         sed -E -i 's/("environment"[[:space:]]*:[[:space:]]*")[^"]+(")/\1production\2/' "$SERVER_CONFIG"
         sed -E -i 's/("default"[[:space:]]*:[[:space:]]*")[^"]+(")/\1production\2/' "$DATABASE_CONFIG"
 
-        ./bin/entity-server banner
-        nohup ./bin/entity-server >> "$STDOUT_LOG" 2>&1 &
+        "$SERVER_BIN" banner
+        nohup "$SERVER_BIN" >> "$STDOUT_LOG" 2>&1 &
         SERVER_PID=$!
         echo "$SERVER_PID" > "$PID_FILE"
 

package/template/scripts/update-server.ps1

@@ -1,10 +1,14 @@
-# update-server.ps1 — entity-server / entity-cli 바이너리 업데이트
+# update-server.ps1 — entity-server / entity-cli 바이너리 및 파일 업데이트
 #
 # 사용법:
 #   .\scripts\update-server.ps1             # 도움말
 #   .\scripts\update-server.ps1 version     # 현재 버전 + 최신 버전 확인
 #   .\scripts\update-server.ps1 latest      # 최신 버전으로 업데이트
 #   .\scripts\update-server.ps1 1.5.0       # 특정 버전으로 업데이트
+#
+# 업데이트 대상:
+#   - 바이너리: entity-server, entity-cli
+#   - 파일: scripts/  samples/  (configs/ entities/ docs/ 제외)
 
 param([string]$Action = "")
 
@@ -12,14 +16,75 @@ $ErrorActionPreference = "Stop"
 
 $REPO        = "ehfuse/entity-server"
 $BINARIES    = @("entity-server", "entity-cli")
+$DIST_DIRS   = @("scripts", "samples")
 $PLATFORM    = "windows"
 $ARCH_TAG    = "x64"
 $ProjectRoot = Split-Path -Parent $PSScriptRoot
 
+function Get-RunningServerPid {
+    $PidFile = Join-Path $ProjectRoot ".run\entity-server.pid"
+    if (Test-Path $PidFile) {
+        $pidValue = (Get-Content $PidFile -ErrorAction SilentlyContinue | Select-Object -First 1).Trim()
+        if ($pidValue -match '^\d+$') {
+            try {
+                $p = Get-Process -Id ([int]$pidValue) -ErrorAction Stop
+                if ($p) { return [int]$pidValue }
+            } catch {}
+        }
+    }
+
+    $proc = Get-Process -Name "entity-server" -ErrorAction SilentlyContinue | Select-Object -First 1
+    if ($proc) { return [int]$proc.Id }
+    return $null
+}
+
+function Ensure-ServerStopped {
+    $pidValue = Get-RunningServerPid
+    if (-not $pidValue) { return }
+
+    Write-Host ""
+    Write-Host "⚠️  현재 Entity Server가 실행 중입니다."
+    try {
+        $p = Get-Process -Id $pidValue -ErrorAction Stop
+        Write-Host ("PID: {0}  Name: {1}  Start: {2}" -f $p.Id, $p.ProcessName, $p.StartTime)
+    } catch {}
+    Write-Host ""
+
+    $answer = Read-Host "업데이트를 위해 서버를 중지할까요? [y/N]"
+    if ($answer -notmatch '^[Yy](es)?$') {
+        Write-Host "❌ 업데이트를 취소했습니다."
+        exit 1
+    }
+
+    $RunScript = Join-Path $ProjectRoot "scripts\run.ps1"
+    if (Test-Path $RunScript) {
+        try {
+            & $RunScript stop
+        } catch {}
+    } else {
+        try {
+            Stop-Process -Id $pidValue -Force -ErrorAction Stop
+        } catch {}
+    }
+
+    Start-Sleep -Milliseconds 200
+    $still = Get-RunningServerPid
+    if ($still) {
+        Write-Host "❌ 서버 중지에 실패했습니다. 업데이트를 중단합니다."
+        exit 1
+    }
+
+    Write-Host "✅ 서버 중지 완료"
+}
+
 # ── 현재 버전 확인 ────────────────────────────────────────────────────────────
 
 function Get-CurrentVer {
-    $BinPath = Join-Path $ProjectRoot "entity-server.exe"
+    $BinPath = Join-Path $ProjectRoot "bin\entity-server.exe"
+    if (-not (Test-Path $BinPath)) {
+        $LegacyBin = Join-Path $ProjectRoot "entity-server.exe"
+        if (Test-Path $LegacyBin) { $BinPath = $LegacyBin }
+    }
     if (Test-Path $BinPath) {
         try {
             $out = & $BinPath --version 2>$null
@@ -47,6 +112,8 @@ function Install-Version([string]$TargetVer) {
     $TargetVer = $TargetVer -replace '^v', ''
     $CurrentVer = Get-CurrentVer
 
+    Ensure-ServerStopped
+
     Write-Host ""
     Write-Host "📦 entity-server v$TargetVer 다운로드 중... ($PLATFORM-$ARCH_TAG)"
     Write-Host ""
@@ -54,7 +121,11 @@ function Install-Version([string]$TargetVer) {
     foreach ($Bin in $BINARIES) {
         $FileName = "$Bin-$PLATFORM-$ARCH_TAG.exe"
         $Url      = "https://github.com/$REPO/releases/download/v$TargetVer/$FileName"
-        $Dest     = Join-Path $ProjectRoot "$Bin.exe"
+        $BinDir   = Join-Path $ProjectRoot "bin"
+        if (-not (Test-Path $BinDir)) {
+            New-Item -ItemType Directory -Path $BinDir | Out-Null
+        }
+        $Dest     = Join-Path $BinDir "$Bin.exe"
         $Tmp      = "$Dest.tmp"
 
         Write-Host ("  ↓ {0,-35}" -f $FileName) -NoNewline
@@ -71,22 +142,107 @@ function Install-Version([string]$TargetVer) {
         }
     }
 
+    Install-Dist $TargetVer
+
     Write-Host ""
     Write-Host "✅ 업데이트 완료: v$CurrentVer → v$TargetVer"
     Write-Host "   서버를 재시작하면 새 버전이 적용됩니다."
 }
 
+# ── dist 파일 업데이트 (scripts / samples) ──────────────────────────────────
+
+function Install-Dist([string]$TargetVer) {
+    $TargetVer = $TargetVer -replace '^v', ''
+    $FileName = "dist.tar.gz"
+    $Url = "https://github.com/$REPO/releases/download/v$TargetVer/$FileName"
+    $TmpTar = Join-Path $env:TEMP ("entity-server-dist-$TargetVer.tar.gz")
+    $TmpDir = Join-Path $env:TEMP ("entity-server-dist-$TargetVer")
+
+    Write-Host ("  ↓ {0,-35}" -f $FileName) -NoNewline
+    try {
+        Invoke-WebRequest -Uri $Url -OutFile $TmpTar -UseBasicParsing
+        Write-Host "✓"
+    } catch {
+        Write-Host "✗ 실패 (업데이트 스킵)"
+        Write-Host "    URL: $Url"
+        Write-Host "    ⚠️  dist.tar.gz 가 릴리스에 없습니다. 바이너리만 업데이트됩니다."
+        return
+    }
+
+    if (Test-Path $TmpDir) {
+        Remove-Item -Recurse -Force $TmpDir
+    }
+    New-Item -ItemType Directory -Path $TmpDir | Out-Null
+
+    # tar.exe 사용 (Windows 10+/PowerShell 5+ 기본 포함 환경 가정)
+    $TarCmd = Get-Command tar -ErrorAction SilentlyContinue
+    if (-not $TarCmd) {
+        Write-Host "    ⚠️  tar 명령을 찾지 못해 dist 동기화를 건너뜁니다."
+        if (Test-Path $TmpTar) { Remove-Item -Force $TmpTar }
+        return
+    }
+
+    try {
+        & tar -xzf $TmpTar -C $TmpDir
+    } catch {
+        Write-Host "    ⚠️  dist 압축 해제 실패: $_"
+        if (Test-Path $TmpTar) { Remove-Item -Force $TmpTar }
+        if (Test-Path $TmpDir) { Remove-Item -Recurse -Force $TmpDir }
+        return
+    }
+
+    $SrcRoot = $TmpDir
+    $HasTopLevel = $false
+    foreach ($Dir in $DIST_DIRS) {
+        if (Test-Path (Join-Path $TmpDir $Dir)) {
+            $HasTopLevel = $true
+            break
+        }
+    }
+
+    if (-not $HasTopLevel) {
+        $FirstSubdir = Get-ChildItem -Path $TmpDir -Directory | Select-Object -First 1
+        if ($FirstSubdir) {
+            $SrcRoot = $FirstSubdir.FullName
+        }
+    }
+
+    Write-Host ""
+    Write-Host "  파일 동기화 (configs/ entities/ docs/ 제외):"
+    foreach ($Dir in $DIST_DIRS) {
+        $Src = Join-Path $SrcRoot $Dir
+        $Dest = Join-Path $ProjectRoot $Dir
+        if (Test-Path $Src) {
+            if (Test-Path $Dest) {
+                Remove-Item -Recurse -Force $Dest
+            }
+            Copy-Item -Recurse -Force $Src $Dest
+            Write-Host ("    ✔ {0,-20}" -f ("$Dir/"))
+        } else {
+            Write-Host ("    – {0,-20} (릴리스에 없음, 스킵)" -f ("$Dir/"))
+        }
+    }
+
+    if (Test-Path $TmpTar) { Remove-Item -Force $TmpTar }
+    if (Test-Path $TmpDir) { Remove-Item -Recurse -Force $TmpDir }
+}
+
 # ── 서브커맨드 분기 ───────────────────────────────────────────────────────────
 
 switch ($Action) {
     "" {
-        Write-Host "update-server.ps1 — entity-server / entity-cli 바이너리 업데이트"
+        Write-Host "update-server.ps1 — entity-server / entity-cli 바이너리 및 파일 업데이트"
         Write-Host ""
         Write-Host "사용법:"
         Write-Host "  .\scripts\update-server.ps1 version        현재 버전 + 최신 버전 확인"
         Write-Host "  .\scripts\update-server.ps1 latest         최신 버전으로 업데이트"
         Write-Host "  .\scripts\update-server.ps1 <버전>         특정 버전으로 업데이트"
         Write-Host ""
+        Write-Host "업데이트 대상:"
+        Write-Host "  바이너리   entity-server  entity-cli"
+        Write-Host "  파일    scripts/  samples/"
+        Write-Host "  제외     configs/  entities/  docs/  (local 설정 보존)"
+        Write-Host ""
         Write-Host "예시:"
         Write-Host "  .\scripts\update-server.ps1 version"
         Write-Host "  .\scripts\update-server.ps1 latest"

package/template/scripts/update-server.sh

@@ -1,11 +1,15 @@
 #!/bin/bash
-# update-server.sh — entity-server / entity-cli 바이너리 업데이트
+# update-server.sh — entity-server / entity-cli 바이너리 및 파일 업데이트
 #
 # 사용법:
 #   ./scripts/update-server.sh             # 도움말
 #   ./scripts/update-server.sh version     # 현재 버전 + 최신 버전 확인
 #   ./scripts/update-server.sh latest      # 최신 버전으로 업데이트
 #   ./scripts/update-server.sh 1.5.0       # 특정 버전으로 업데이트
+#
+# 업데이트 대상:
+#   - 바이너리: entity-server, entity-cli
+#   - 파일: scripts/  samples/  (configs/ entities/ docs/ 제외)
 
 set -e
 
@@ -13,6 +17,57 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
 REPO="ehfuse/entity-server"
 BINARIES=("entity-server" "entity-cli")
+DIST_DIRS=("scripts" "samples")
+
+_find_running_pid() {
+    local pid_file="$PROJECT_ROOT/.run/entity-server.pid"
+    if [ -f "$pid_file" ]; then
+        local pid
+        pid=$(cat "$pid_file" 2>/dev/null)
+        if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+            echo "$pid"
+            return 0
+        fi
+    fi
+
+    pgrep -f "${PROJECT_ROOT}/(bin/)?entity-server( |$)" | head -n 1
+}
+
+_ensure_server_stopped() {
+    local pid
+    pid="$(_find_running_pid)"
+
+    if [ -z "$pid" ]; then
+        return 0
+    fi
+
+    echo ""
+    echo "⚠️  현재 Entity Server가 실행 중입니다."
+    ps -p "$pid" -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
+        kill "$pid" 2>/dev/null || true
+    fi
+
+    sleep 0.2
+    pid="$(_find_running_pid)"
+    if [ -n "$pid" ]; then
+        echo "❌ 서버 중지에 실패했습니다. 업데이트를 중단합니다."
+        exit 1
+    fi
+
+    echo "✅ 서버 중지 완료"
+}
 
 # ── 플랫폼 감지 ───────────────────────────────────────────────────────────────
 
@@ -41,7 +96,10 @@ esac
 # ── 현재 버전 확인 ────────────────────────────────────────────────────────────
 
 _current_ver() {
-    local bin="$PROJECT_ROOT/entity-server"
+    local bin="$PROJECT_ROOT/bin/entity-server"
+    if [ ! -x "$bin" ] && [ -x "$PROJECT_ROOT/entity-server" ]; then
+        bin="$PROJECT_ROOT/entity-server"
+    fi
     if [ -x "$bin" ]; then
         "$bin" --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1 || echo "(알 수 없음)"
     else
@@ -95,14 +153,19 @@ _install() {
     local current_ver
     current_ver="$(_current_ver)"
 
+    _ensure_server_stopped
+
     echo ""
     echo "📦 entity-server v${target_ver} 다운로드 중... (${PLATFORM}-${ARCH_TAG})"
     echo ""
 
+    # 바이너리 다운로드
+    mkdir -p "$PROJECT_ROOT/bin"
+
     for BIN in "${BINARIES[@]}"; do
         local file="${BIN}-${PLATFORM}-${ARCH_TAG}"
         local url="https://github.com/${REPO}/releases/download/v${target_ver}/${file}"
-        local dest="$PROJECT_ROOT/$BIN"
+        local dest="$PROJECT_ROOT/bin/$BIN"
 
         printf "  ↓ %-32s" "$file"
         if _download "$url" "$dest" 2>/dev/null; then
@@ -114,24 +177,89 @@ _install() {
         fi
     done
 
+    # scripts / samples 업데이트
+    _install_dist "$target_ver"
+
     echo ""
     echo "✅ 업데이트 완료: v${current_ver} → v${target_ver}"
     echo "   서버를 재시작하면 새 버전이 적용됩니다."
 }
 
+# ── dist 파일 업데이트 (scripts / samples) ──────────────────────────────────────
+
+_install_dist() {
+    local target_ver="$1"
+    local file="dist.tar.gz"
+    local url="https://github.com/${REPO}/releases/download/v${target_ver}/${file}"
+    local tmp_tar="/tmp/entity-server-dist-${target_ver}.tar.gz"
+    local tmp_dir="/tmp/entity-server-dist-${target_ver}"
+
+    printf "  ↓ %-32s" "$file"
+    if ! _download "$url" "$tmp_tar" 2>/dev/null; then
+        echo "✗ 실패 (업데이트 스킵)"
+        echo "    URL: $url"
+        echo "    ⚠️  dist.tar.gz 가 릴리스에 없익니다. 바이너리만 업데이트됨."
+        return 0
+    fi
+    echo "✓"
+
+    rm -rf "$tmp_dir"
+    mkdir -p "$tmp_dir"
+    tar -xzf "$tmp_tar" -C "$tmp_dir" 2>/dev/null
+
+    # 아카이브 내부 디렉토리 구조 자동 탐지 (top-level 또는 서브디렉토리)
+    local src_root="$tmp_dir"
+    local found_dir="false"
+    for dir in "${DIST_DIRS[@]}"; do
+        if [ -d "${tmp_dir}/${dir}" ]; then
+            found_dir="true"
+            break
+        fi
+    done
+    if [ "$found_dir" = "false" ]; then
+        # tar가 서브디렉토리 하나로 풌주는 경우 (예: entity-server-1.5.0/)
+        local subdir
+        subdir="$(ls -1 "$tmp_dir" | head -1)"
+        if [ -n "$subdir" ] && [ -d "${tmp_dir}/${subdir}" ]; then
+            src_root="${tmp_dir}/${subdir}"
+        fi
+    fi
+
+    echo ""
+    echo "  파일 동기화 (configs/ entities/ 제외):"
+    for DIR in "${DIST_DIRS[@]}"; do
+        local src="${src_root}/${DIR}"
+        local dest="${PROJECT_ROOT}/${DIR}"
+        if [ -d "$src" ]; then
+            rm -rf "$dest"
+            cp -r "$src" "$dest"
+            printf "    ✔ %-20s\n" "${DIR}/"
+        else
+            printf "    – %-20s (릴리스에 없음, 스킵)\n" "${DIR}/"
+        fi
+    done
+
+    rm -rf "$tmp_dir" "$tmp_tar"
+}
+
 # ── 서브커맨드 분기 ───────────────────────────────────────────────────────────
 
 ARG="${1:-}"
 
 case "$ARG" in
     "")
-        echo "update-server.sh — entity-server / entity-cli 바이너리 업데이트"
+        echo "update-server.sh — entity-server / entity-cli 바이너리 및 파일 업데이트"
         echo ""
         echo "사용법:"
         echo "  ./scripts/update-server.sh version        현재 버전 + 최신 버전 확인"
         echo "  ./scripts/update-server.sh latest         최신 버전으로 업데이트"
         echo "  ./scripts/update-server.sh <버전>         특정 버전으로 업데이트"
         echo ""
+        echo "업데이트 대상:"
+        echo "  바이너리   entity-server  entity-cli"
+        echo "  파일    scripts/  samples/"
+        echo "  제외     configs/  entities/  docs/  (local 설정 보존)"
+        echo ""
         echo "예시:"
         echo "  ./scripts/update-server.sh version"
         echo "  ./scripts/update-server.sh latest"