create-entity-server 0.0.15 → 0.0.23

package/template/samples/python/example.py

@@ -15,7 +15,7 @@ es = EntityServerClient()
 
 # 목록 조회
 result = es.list("product", page=1, limit=10)
-print(f"List: {len(result.get('data', []))} items")
+print(f"List: {result.get('data', {}).get('total', 0)} items")
 
 # 생성
 created = es.submit("product", {
@@ -34,16 +34,17 @@ print(f"Get: {item['data']['name']}")
 es.submit("product", {"seq": seq, "price": 39000})
 print("Updated")
 
-# 필터 검색
+# 커스텀 SQL 검색
 results = es.query("product",
-    filter=[{"field": "category", "op": "eq", "value": "peripherals"}],
-    page=1, limit=5,
+    sql="SELECT seq, name, category FROM product WHERE category = ?",
+    params=["peripherals"],
+    limit=5,
 )
-print(f"Query: {len(results.get('data', []))} results")
+print(f"Query: {len(results.get('data', {}).get('items', []))} results")
 
 # 이력 조회
 hist = es.history("product", seq)
-print(f"History: {len(hist.get('data', []))} entries")
+print(f"History: {hist.get('data', {}).get('total', 0)} entries")
 
 # 삭제
 es.delete("product", seq)

package/template/samples/react/src/example.tsx

@@ -4,16 +4,15 @@
  * 설정:
  *   1. .env 에 VITE_ENTITY_SERVER_URL=http://localhost:47200 추가
  *   2. 로그인 시 entityServer.login(email, password) 호출
- *   3. 이후 훅으로 데이터 조회/수정
+ *   3. 이후 client 메서드로 데이터 조회/수정
  */
 
-import { useState } from "react";
-import {
-    useEntityDelete,
-    useEntityGet,
-    useEntityList,
-    useEntitySubmit,
-} from "./hooks/useEntity";
+// @ts-ignore
+import { useEffect, useState } from "react";
+// @ts-ignore
+import { useEntityServer } from "entity-server-client/react";
+// @ts-ignore
+import type { EntityListResult } from "entity-server-client";
 
 interface Product {
     seq: number;
@@ -25,27 +24,35 @@ interface Product {
 // ─── 목록 컴포넌트 ─────────────────────────────────────────────────────────
 
 export function ProductList() {
+    const { client, isPending, error, del } = useEntityServer();
     const [page, setPage] = useState(1);
-    const { data, isLoading, error } = useEntityList<Product>("product", {
-        page,
-        limit: 20,
-    });
-    const deleteMut = useEntityDelete("product");
+    const [result, setResult] = useState<EntityListResult<Product> | null>(
+        null,
+    );
+    const [loading, setLoading] = useState(false);
+
+    useEffect(() => {
+        setLoading(true);
+        client
+            .list<Product>("product", { page, limit: 20 })
+            .then((r) => setResult(r.data))
+            .finally(() => setLoading(false));
+    }, [client, page]);
 
-    if (isLoading) return <p>로딩 중...</p>;
-    if (error) return <p>에러: {(error as Error).message}</p>;
+    if (loading) return <p>로딩 중...</p>;
+    if (error) return <p>에러: {error.message}</p>;
 
     return (
         <div>
-            <h2>상품 목록 ({data?.total ?? 0}건)</h2>
+            <h2>상품 목록 ({result?.total ?? 0}건)</h2>
             <ul>
-                {data?.data.map((item) => (
+                {result?.items.map((item) => (
                     <li key={item.seq}>
                         [{item.seq}] {item.name} — {item.price.toLocaleString()}
                         원
                         <button
-                            onClick={() => deleteMut.mutate(item.seq)}
-                            disabled={deleteMut.isPending}
+                            onClick={() => del("product", item.seq)}
+                            disabled={isPending}
                         >
                             삭제
                         </button>
@@ -67,10 +74,19 @@ export function ProductList() {
 // ─── 단건 조회 컴포넌트 ─────────────────────────────────────────────────────
 
 export function ProductDetail({ seq }: { seq: number }) {
-    const { data, isLoading } = useEntityGet<Product>("product", seq);
+    const { client } = useEntityServer();
+    const [item, setItem] = useState<Product | null>(null);
+    const [loading, setLoading] = useState(true);
+
+    useEffect(() => {
+        client
+            .get<Product>("product", seq)
+            .then((r) => setItem(r.data))
+            .catch(() => setItem(null))
+            .finally(() => setLoading(false));
+    }, [client, seq]);
 
-    if (isLoading) return <p>로딩 중...</p>;
-    const item = data?.data;
+    if (loading) return <p>로딩 중...</p>;
     if (!item) return <p>상품을 찾을 수 없습니다.</p>;
 
     return (
@@ -85,13 +101,13 @@ export function ProductDetail({ seq }: { seq: number }) {
 // ─── 생성/수정 폼 컴포넌트 ──────────────────────────────────────────────────
 
 export function ProductForm({ seq }: { seq?: number }) {
-    const submitMut = useEntitySubmit("product");
+    const { submit, isPending } = useEntityServer();
     const [form, setForm] = useState({ name: "", price: 0, category: "" });
 
     const handleSubmit = async (e: React.FormEvent) => {
         e.preventDefault();
         // seq 있으면 수정, 없으면 생성
-        await submitMut.mutateAsync(seq ? { ...form, seq } : form);
+        await submit("product", seq ? { ...form, seq } : form);
         alert(seq ? "수정 완료" : "등록 완료");
     };
 
@@ -119,7 +135,7 @@ export function ProductForm({ seq }: { seq?: number }) {
                     setForm((f) => ({ ...f, category: e.target.value }))
                 }
             />
-            <button type="submit" disabled={submitMut.isPending}>
+            <button type="submit" disabled={isPending}>
                 {seq ? "수정" : "등록"}
             </button>
         </form>

package/template/samples/swift/EntityServerClient.swift

@@ -8,8 +8,7 @@
  *   let client = EntityServerClient(
  *       baseUrl:    "http://your-server:47200",
  *       apiKey:     "your-api-key",
- *       hmacSecret: "your-hmac-secret",
- *       magicLen:   4   // 서버 packet_magic_len 과 동일
+ *       hmacSecret: "your-hmac-secret"
  *   )
  *   let result = try await client.list("product")
  *
@@ -33,7 +32,8 @@ public final class EntityServerClient {
     private let baseURL: URL
     private let apiKey: String
     private let hmacSecret: String
-    private let magicLen: Int
+    private var token: String
+    private let encryptRequests: Bool
     private let session: URLSession
     private var activeTxId: String? = nil
 
@@ -41,33 +41,77 @@ public final class EntityServerClient {
         baseUrl: String = "http://localhost:47200",
         apiKey: String = "",
         hmacSecret: String = "",
-        magicLen: Int = 4,
+        token: String = "",
+        /// true 이면 POST 요청 바디를 XChaCha20-Poly1305로 암호화합니다.
+        encryptRequests: Bool = false,
         session: URLSession = .shared
     ) {
         self.baseURL = URL(string: baseUrl.removingSuffix("/"))!
         self.apiKey = apiKey
         self.hmacSecret = hmacSecret
-        self.magicLen = magicLen
+        self.token = token
+        self.encryptRequests = encryptRequests
         self.session = session
     }
 
+    /** JWT Bearer 토큰을 설정합니다. HMAC 모드와 배타적으로 사용합니다. */
+    public func setToken(_ newToken: String) { token = newToken }
+
     // ─── CRUD ─────────────────────────────────────────────────────────
 
-    public func get(entity: String, seq: Int64) async throws -> [String: Any] {
-        try await request(method: "GET", path: "/v1/entity/\(entity)/\(seq)")
+    public func get(entity: String, seq: Int64, skipHooks: Bool = false) async throws -> [String: Any] {
+        let q = skipHooks ? "?skipHooks=true" : ""
+        return try await request(method: "GET", path: "/v1/entity/\(entity)/\(seq)\(q)")
+    }
+
+    /// 조건으로 단건 조회 (POST + conditions body)
+    ///
+    /// `conditions` 는 index/hash/unique 필드에만 사용 가능합니다.
+    /// 조건에 맞는 행이 없으면 404 오류가 발생합니다.
+    public func find(entity: String, conditions: [String: Any], skipHooks: Bool = false) async throws -> [String: Any] {
+        let q = skipHooks ? "?skipHooks=true" : ""
+        let body = try JSONSerialization.data(withJSONObject: conditions)
+        return try await request(method: "POST", path: "/v1/entity/\(entity)/find\(q)", body: body)
     }
 
-    public func list(entity: String, page: Int = 1, limit: Int = 20) async throws -> [String: Any] {
-        try await request(method: "GET", path: "/v1/entity/\(entity)/list?page=\(page)&limit=\(limit)")
+    /// 목록 조회 (POST + conditions body)
+    ///
+    /// `fields`를 미지정하면 기본적으로 인덱스 필드만 반환합니다 (가장 빠름).
+    /// 전체 필드 반환이 필요하면 `fields: ["*"]` 를 지정하세요.
+    /// `conditions` 는 index/hash/unique 필드에만 사용 가능합니다.
+    public func list(
+        entity: String,
+        page: Int = 1,
+        limit: Int = 20,
+        orderBy: String? = nil,
+        fields: [String]? = nil,
+        conditions: [String: Any]? = nil
+    ) async throws -> [String: Any] {
+        var qParts = ["page=\(page)", "limit=\(limit)"]
+        if let orderBy = orderBy { qParts.append("order_by=\(orderBy)") }
+        if let fields = fields, !fields.isEmpty { qParts.append("fields=\(fields.joined(separator: ","))") }
+        let body = try JSONSerialization.data(withJSONObject: conditions ?? [:])
+        return try await request(method: "POST", path: "/v1/entity/\(entity)/list?\(qParts.joined(separator: "&"))", body: body)
     }
 
-    public func count(entity: String) async throws -> [String: Any] {
-        try await request(method: "GET", path: "/v1/entity/\(entity)/count")
+    /// 건수 조회
+    public func count(entity: String, conditions: [String: Any]? = nil) async throws -> [String: Any] {
+        let body = try JSONSerialization.data(withJSONObject: conditions ?? [:])
+        return try await request(method: "POST", path: "/v1/entity/\(entity)/count", body: body)
     }
 
-    public func query(entity: String, filter: [[String: Any]], page: Int = 1, limit: Int = 20) async throws -> [String: Any] {
-        let body = try JSONSerialization.data(withJSONObject: filter)
-        return try await request(method: "POST", path: "/v1/entity/\(entity)/query?page=\(page)&limit=\(limit)", body: body)
+    /// 커스텀 SQL 조회 (SELECT 전용, 인덱스 테이블만, JOIN 지원)
+    /// 사용자 입력은 반드시 `params` 로 바인딩하세요 (SQL Injection 방지).
+    public func query(
+        entity: String,
+        sql: String,
+        params: [Any]? = nil,
+        limit: Int? = nil
+    ) async throws -> [String: Any] {
+        var bodyDict: [String: Any] = ["sql": sql, "params": params ?? []]
+        if let limit = limit { bodyDict["limit"] = limit }
+        let body = try JSONSerialization.data(withJSONObject: bodyDict)
+        return try await request(method: "POST", path: "/v1/entity/\(entity)/query", body: body)
     }
 
     /// 트랜잭션 시작 — 서버에 트랜잭션 큐를 등록하고 transaction_id 를 반환합니다.
@@ -104,18 +148,23 @@ public final class EntityServerClient {
         return try await request(method: "POST", path: "/v1/transaction/commit/\(txId)")
     }
 
-    public func submit(entity: String, data: [String: Any], transactionId: String? = nil) async throws -> [String: Any] {
+    public func submit(entity: String, data: [String: Any], transactionId: String? = nil, skipHooks: Bool = false) async throws -> [String: Any] {
         let body = try JSONSerialization.data(withJSONObject: data)
         var extra: [String: String] = [:]
         if let txId = transactionId ?? activeTxId { extra["X-Transaction-ID"] = txId }
-        return try await request(method: "POST", path: "/v1/entity/\(entity)/submit", body: body, extraHeaders: extra)
+        let q = skipHooks ? "?skipHooks=true" : ""
+        return try await request(method: "POST", path: "/v1/entity/\(entity)/submit\(q)", body: body, extraHeaders: extra)
     }
 
-    public func delete(entity: String, seq: Int64, transactionId: String? = nil, hard: Bool = false) async throws -> [String: Any] {
-        let q = hard ? "?hard=true" : ""
+    /// 삭제. 서버는 POST /delete/:seq 로만 처리합니다.
+    public func delete(entity: String, seq: Int64, transactionId: String? = nil, hard: Bool = false, skipHooks: Bool = false) async throws -> [String: Any] {
+        var qParts: [String] = []
+        if hard { qParts.append("hard=true") }
+        if skipHooks { qParts.append("skipHooks=true") }
+        let q = qParts.isEmpty ? "" : "?" + qParts.joined(separator: "&")
         var extra: [String: String] = [:]
         if let txId = transactionId ?? activeTxId { extra["X-Transaction-ID"] = txId }
-        return try await request(method: "DELETE", path: "/v1/entity/\(entity)/delete/\(seq)\(q)", extraHeaders: extra)
+        return try await request(method: "POST", path: "/v1/entity/\(entity)/delete/\(seq)\(q)", extraHeaders: extra)
     }
 
     public func history(entity: String, seq: Int64, page: Int = 1, limit: Int = 50) async throws -> [String: Any] {
@@ -238,25 +287,38 @@ public final class EntityServerClient {
         var req = URLRequest(url: url)
         req.httpMethod = method
 
-        let bodyStr = body.map { String(data: $0, encoding: .utf8) ?? "" } ?? ""
-        let timestamp = String(Int(Date().timeIntervalSince1970))
-        let nonce = UUID().uuidString
-        let signature = try sign(method: method, path: path, timestamp: timestamp, nonce: nonce, body: bodyStr)
+        // 요청 바디 결정: encryptRequests 시 POST 바디를 암호화합니다.
+        var requestBody = body
+        var requestContentType = "application/json"
+        if let body = body, encryptRequests || packetEncryption {
+            requestBody = try encryptPacket(body)
+            requestContentType = "application/octet-stream"
+        }
 
-        req.setValue("application/json", forHTTPHeaderField: "Content-Type")
-        req.setValue(apiKey, forHTTPHeaderField: "X-API-Key")
-        req.setValue(timestamp, forHTTPHeaderField: "X-Timestamp")
-        req.setValue(nonce, forHTTPHeaderField: "X-Nonce")
-        req.setValue(signature, forHTTPHeaderField: "X-Signature")
+        let bodyForSign = requestBody ?? Data()
+        let isHmacMode = !apiKey.isEmpty && !hmacSecret.isEmpty
+
+        req.setValue(requestContentType, forHTTPHeaderField: "Content-Type")
+        if isHmacMode {
+            let timestamp = String(Int(Date().timeIntervalSince1970))
+            let nonce = UUID().uuidString
+            let signature = try sign(method: method, path: path, timestamp: timestamp, nonce: nonce, bodyData: bodyForSign)
+            req.setValue(apiKey,     forHTTPHeaderField: "X-API-Key")
+            req.setValue(timestamp,  forHTTPHeaderField: "X-Timestamp")
+            req.setValue(nonce,      forHTTPHeaderField: "X-Nonce")
+            req.setValue(signature,  forHTTPHeaderField: "X-Signature")
+        } else if !token.isEmpty {
+            req.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
+        }
         extraHeaders.forEach { req.setValue($0.value, forHTTPHeaderField: $0.key) }
-        req.httpBody = body
+        req.httpBody = requestBody
 
         let (data, response) = try await session.data(for: req)
         let http = response as! HTTPURLResponse
-        let contentType = http.value(forHTTPHeaderField: "Content-Type") ?? ""
+        let respContentType = http.value(forHTTPHeaderField: "Content-Type") ?? ""
 
         // 패킷 암호화 응답: application/octet-stream → 복호화
-        if contentType.contains("application/octet-stream") {
+        if respContentType.contains("application/octet-stream") {
             return try decryptPacket(data)
         }
 
@@ -266,14 +328,50 @@ public final class EntityServerClient {
         return json
     }
 
+    /**
+     * 패킷 암호화 키를 유도합니다.
+     * - HMAC 모드: HKDF-SHA256(hmac_secret, "entity-server:packet-encryption")
+     * - JWT  모드: SHA256(token)
+     */
+    private func derivePacketKey() throws -> [UInt8] {
+        if !token.isEmpty && hmacSecret.isEmpty {
+            return Digest.sha256(Array(token.utf8))
+        }
+        return try HKDF(
+            password: Array(hmacSecret.utf8),
+            salt: Array("entity-server:hkdf:v1".utf8),
+            info: Array("entity-server:packet-encryption".utf8),
+            keyLength: 32,
+            variant: .sha256
+        ).calculate()
+    }
+
+    /**
+     * XChaCha20-Poly1305 패킷 암호화
+     * 포맷: [magic:magicLen][nonce:24][ciphertext+tag]
+     * 키: HKDF-SHA256(hmac_secret, "entity-server:packet-encryption")
+     * magicLen: 2 + key[31] % 14
+     */
+    private func encryptPacket(_ data: Data) throws -> Data {
+        let key = try derivePacketKey()
+        var generator = SystemRandomNumberGenerator()
+        let magicLen = 2 + Int(key[31]) % 14
+        let magic = (0..<magicLen).map { _ in generator.next() as UInt8 }
+        let nonce  = (0..<24).map     { _ in generator.next() as UInt8 }
+        let xchacha = XChaCha20Poly1305(key: key, iv: nonce, aad: [])
+        let ciphertext = try xchacha.encrypt(Array(data))
+        return Data(magic + nonce + ciphertext)
+    }
+
     /**
      * XChaCha20-Poly1305 패킷 복호화
      * 포맷: [magic:magicLen][nonce:24][ciphertext+tag]
-     * 키: sha256(hmac_secret)
+     * 키: HKDF-SHA256(hmac_secret, "entity-server:packet-encryption")
      */
     private func decryptPacket(_ data: Data) throws -> [String: Any] {
-        let key = Array(SHA2(variant: .sha256).calculate(for: Array(hmacSecret.utf8)))
+        let key = try derivePacketKey()
         let bytes = Array(data)
+        let magicLen = 2 + Int(key[31]) % 14
         let nonce = Array(bytes[magicLen..<(magicLen + 24)])
         let ciphertext = Array(bytes[(magicLen + 24)...])
 
@@ -287,10 +385,11 @@ public final class EntityServerClient {
         return json
     }
 
-    /** HMAC-SHA256 서명 */
-    private func sign(method: String, path: String, timestamp: String, nonce: String, body: String) throws -> String {
-        let payload = [method, path, timestamp, nonce, body].joined(separator: "|")
-        let mac = try HMAC(key: Array(hmacSecret.utf8), variant: .sha256).authenticate(Array(payload.utf8))
+    /** HMAC-SHA256 서명. bodyData 는 JSON 또는 암호화된 바이너리 모두 지원합니다. */
+    private func sign(method: String, path: String, timestamp: String, nonce: String, bodyData: Data) throws -> String {
+        var payload = "\(method)|\(path)|\(timestamp)|\(nonce)|".data(using: .utf8)!
+        payload.append(bodyData)
+        let mac = try HMAC(key: Array(hmacSecret.utf8), variant: .sha256).authenticate(Array(payload))
         return mac.map { String(format: "%02x", $0) }.joined()
     }
 }
@@ -301,6 +400,13 @@ private struct XChaCha20Poly1305 {
     let iv: [UInt8]
     let aad: [UInt8]
 
+    func encrypt(_ plaintext: [UInt8]) throws -> [UInt8] {
+        let chacha = try ChaCha20(key: key, iv: iv)
+        let ct = try chacha.encrypt(plaintext)
+        let poly = try Poly1305(key: chacha.keystream().prefix(32)).authenticate(ct + aad)
+        return ct + poly
+    }
+
     func decrypt(_ ciphertext: [UInt8]) throws -> [UInt8] {
         // CryptoSwift ChaCha20.Poly1305 AEAD - tag는 마지막 16바이트
         let tag = Array(ciphertext.suffix(16))

package/template/scripts/run.ps1

@@ -83,6 +83,10 @@ function Stop-Server {
 
 function Show-Status {
     $ServerBin = Join-Path $ProjectRoot "bin\entity-server.exe"
+    if (-not (Test-Path $ServerBin)) {
+        $LegacyBin = Join-Path $ProjectRoot "entity-server.exe"
+        if (Test-Path $LegacyBin) { $ServerBin = $LegacyBin }
+    }
     if (Is-Running) {
         & $ServerBin banner-status RUNNING
         if ($Language -eq "en") { Write-Host "Stop: .\run.ps1 stop" }
@@ -149,9 +153,14 @@ if (-not (Test-Path $DatabaseConfig)) {
 }
 $ServerBin = Join-Path $ProjectRoot "bin\entity-server.exe"
 if (-not (Test-Path $ServerBin)) {
-    if ($Language -eq "en") { Write-Host "X bin/entity-server.exe not found" }
-    else { Write-Host "X bin/entity-server.exe 파일이 없습니다" }
-    exit 1
+    $LegacyBin = Join-Path $ProjectRoot "entity-server.exe"
+    if (Test-Path $LegacyBin) {
+        $ServerBin = $LegacyBin
+    } else {
+        if ($Language -eq "en") { Write-Host "X entity-server.exe not found (bin/entity-server.exe or .\entity-server.exe)" }
+        else { Write-Host "X entity-server.exe 파일이 없습니다 (bin/entity-server.exe 또는 .\entity-server.exe)" }
+        exit 1
+    }
 }
 
 function Update-JsonField {

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"
 
@@ -203,7 +207,7 @@ show_status() {
     if is_running; then
 		local status_pid
 		status_pid=$(find_pid_by_port)
-        ./bin/entity-server banner-status RUNNING
+        "$SERVER_BIN" banner-status RUNNING
         if [ "$LANGUAGE" = "en" ]; then
 			if [ -n "$status_pid" ]; then
 				echo "PID: $status_pid (detected by port)"
@@ -216,7 +220,7 @@ show_status() {
             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
@@ -289,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
@@ -320,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)
@@ -345,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

@@ -21,10 +21,70 @@ $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
@@ -52,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 ""
@@ -59,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