개발 서버 실행 로그 정리

docs/deploy.md

@@ -9,6 +9,8 @@
 | 개발 | `npm run dev` | 로컬 테스트, 개발 서버 |
 | 프로덕션 | `npm run build` | NAS 배포, 운영 서버 |
 
+> `npm run dev`는 프로젝트 전용 실행 스크립트를 통해 Localhost, Local IP, Admin, Tailwind Viewer 링크만 요약 출력한다.
+
 ---
 
 ## 로컬 개발
@@ -67,6 +69,7 @@ docker exec sori-studio-db psql -U sori_studio -d sori_studio -c 'SELECT count(*
 
 - 개발 서버: http://127.0.0.1:43117
 - 관리자: http://127.0.0.1:43117/admin
+- Tailwind Viewer: http://127.0.0.1:43117/_tailwind/
 
 ---
 

docs/history.md

@@ -1,5 +1,13 @@
 # 의사결정 이력
 
+## 2026-05-01 v0.0.13
+
+### 개발 서버 로그 요약 방식 결정
+
+Nuxt 개발 서버의 기본 로그는 프레임워크 상태와 빌드 이벤트를 자세히 보여주지만, 일상적인 로컬 개발에서는 접속 링크만 빠르게 확인하는 편이 더 효율적이다. 따라서 `npm run dev`는 프로젝트 전용 래퍼 스크립트로 Nuxt dev 서버를 실행하고, 터미널에는 Localhost, Local IP, Admin, Tailwind Viewer 링크를 요약 출력한다.
+
+오류나 경고에 가까운 로그는 계속 터미널에 남긴다. 개발 서버 실행 자체는 Nuxt CLI를 그대로 사용하되 출력만 정리해, 프레임워크 동작 방식은 바꾸지 않고 로컬 사용성만 개선한다.
+
 ## 2026-05-01 v0.0.12
 
 ### 제목과 본문 입력 흐름 보정

docs/map.md

@@ -122,6 +122,7 @@
 | assets/css/main.css | 전역 스타일 |
 | composables/useMenuState.js | 좌측 메뉴 열림 상태 관리 |
 | middleware/admin-auth.global.js | 관리자 페이지 접근 인증 |
+| scripts/dev-server.js | 로컬 개발 서버 링크 요약 출력 |
 | scripts/migrate-development-db.js | 로컬 개발 DB 마이그레이션 실행 |
 | .env.example | 환경 변수 예시 |
 | Dockerfile | NAS 운영 이미지 빌드 |

docs/spec.md

@@ -293,6 +293,6 @@ APP_PORT=43118
 
 ## 버전 관리
 
-- 현재 버전: v0.0.12
+- 현재 버전: v0.0.13
 - 첫 커밋 이후 변경사항을 커밋할 때마다 패치 버전 증가
 - 메이저/마이너 버전은 구조 변경 또는 기능 묶음 단위로 결정

docs/update.md

@@ -1,5 +1,11 @@
 # 업데이트 이력
 
+## v0.0.13
+
+- 개발 서버 실행 로그를 프로젝트 전용 링크 요약 출력으로 정리.
+- `npm run dev`가 `scripts/dev-server.js`를 통해 Nuxt 개발 서버를 실행하도록 수정.
+- 패키지 버전을 0.0.13으로 갱신.
+
 ## v0.0.12
 
 - 관리자 글 제목 입력에서 Enter 입력 시 본문 첫 블록으로 이동하도록 수정.

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "sori.studio",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "sori.studio",
-      "version": "0.0.12",
+      "version": "0.0.13",
       "hasInstallScript": true,
       "dependencies": {
         "@nuxtjs/tailwindcss": "^6.14.0",

package.json

@@ -1,10 +1,10 @@
 {
   "name": "sori.studio",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "nuxt dev --dotenv .env.development --host 127.0.0.1 --port 43117",
+    "dev": "node scripts/dev-server.js",
     "build": "nuxt build",
     "preview": "nuxt preview --dotenv .env.development --host 127.0.0.1 --port 43117",
     "db:migrate:dev": "node scripts/migrate-development-db.js",

scripts/dev-server.js

@@ -0,0 +1,75 @@
+import { spawn } from 'node:child_process'
+
+const host = '127.0.0.1'
+const port = '43117'
+let printedLinks = false
+
+const nuxtProcess = spawn('nuxt', [
+  'dev',
+  '--dotenv',
+  '.env.development',
+  '--host',
+  host,
+  '--port',
+  port
+], {
+  shell: true,
+  stdio: ['inherit', 'pipe', 'pipe']
+})
+
+/**
+ * 개발 서버 링크 출력
+ * @param {string} localUrl - Nuxt 로컬 URL
+ * @returns {void}
+ */
+const printDevLinks = (localUrl) => {
+  const url = new URL(localUrl)
+  const origin = `${url.protocol}//${url.hostname}:${url.port}`
+  const localhostOrigin = `${url.protocol}//localhost:${url.port}`
+
+  console.log('')
+  console.log('sori.studio 개발 서버')
+  console.log(`- Localhost: ${localhostOrigin}/`)
+  console.log(`- Local IP: ${origin}/`)
+  console.log(`- Admin: ${origin}/admin`)
+  console.log(`- Tailwind Viewer: ${origin}/_tailwind/`)
+  console.log('')
+}
+
+/**
+ * Nuxt 로그 처리
+ * @param {Buffer} chunk - 로그 버퍼
+ * @returns {void}
+ */
+const handleNuxtLog = (chunk) => {
+  const text = chunk.toString()
+
+  for (const line of text.split('\n')) {
+    const localMatch = line.match(/Local:\s+(https?:\/\/[^\s]+)/)
+
+    if (localMatch && !printedLinks) {
+      printedLinks = true
+      printDevLinks(localMatch[1])
+      continue
+    }
+
+    if (/(^|\s)(error:|warn:|warning:|failed|fatal|eaddrinuse|cannot)\b/i.test(line)) {
+      console.log(line)
+    }
+  }
+}
+
+nuxtProcess.stdout.on('data', handleNuxtLog)
+nuxtProcess.stderr.on('data', handleNuxtLog)
+
+nuxtProcess.on('close', (code) => {
+  process.exit(code || 0)
+})
+
+process.on('SIGINT', () => {
+  nuxtProcess.kill('SIGINT')
+})
+
+process.on('SIGTERM', () => {
+  nuxtProcess.kill('SIGTERM')
+})