mega-framework 0.1.7 → 0.1.9

package/README.md

@@ -39,6 +39,15 @@ npm test              # 전체 테스트(실 인프라). .env 자동 로드(ADR-
 npm run infra:down    # 인프라 종료
 ```
 
+> **워크스페이스 안내 (ADR-197)** — `sample/crud`·`sample/simple` 은 npm workspaces 라서 모든 의존성이
+> **루트 `node_modules` 로 hoist** 된다. `sample/crud/node_modules` 가 안 생기는 것이 **정상**이며
+> (sample 안에서 `npm install` 을 실행해도 루트에 설치된다), `mega-framework` 는
+> `node_modules/mega-framework → ..` self-link 로 해석된다. 확인: `npm ls --workspace sample-crud`.
+>
+> **yarn 미지원** — yarn v1 은 workspaces 에 루트 `"private": true` 를 요구하는데 본 패키지는 npm 배포
+> 대상(`private: false`)이라 `yarn install` 이 `Workspaces can only be enabled in private projects` 로
+> 실패한다. **npm 만 사용**한다(lockfile 정본 = `package-lock.json` 1벌).
+
 프로젝트 루트에 `mega.config.js`(글로벌) + 앱별 `apps/<name>/app.config.js` 를 둔다.
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mega-framework",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Node.js 마이크로프레임웍 + CLI — Slim의 가벼움 + Rails의 관례",
   "type": "module",
   "engines": {
@@ -69,7 +69,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "lint": "eslint src test",
+    "lint": "eslint src test scripts",
     "typecheck": "tsc -p jsconfig.json --noEmit",
     "build:types": "rm -rf types && tsc -p tsconfig.build.json",
     "format": "prettier -w src test packages",
@@ -79,8 +79,8 @@
     "infra:reset": "docker compose down -v && docker compose up -d --wait",
     "test:integration": "npm run infra:up && vitest run test/integration && npm run infra:down",
     "test:unit": "vitest run test/unit",
+    "adr:index": "node scripts/build-adr-index.js",
     "prepublishOnly": "npm run build:types && npm run lint && npm run typecheck && npm run test:unit",
-    "prepare": "npm run build:types",
     "release": "bash scripts/publish.sh"
   },
   "devDependencies": {

package/sample/crud/.env

@@ -20,6 +20,15 @@
 # NODE_ENV=development
 
 
+# ── dev watch ignore (mega.config.js > watch, ADR-220) ───────────────────────
+# `mega start --watch` 의 ignore 목록(콤마 구분 glob) — **여기가 정본**(숨은 코드 디폴트 없음).
+# "런타임이 스스로 쓰거나 재시작 없이 반영되는" 영역을 나열한다. 폴더명을 바꿨으면 이 줄만 고친다.
+#   locales: dev 의 i18n saveMissing 자동 기입(안 빼면 재시작 무한 루프) / views: EJS 는 dev 에서
+#   매 요청 재컴파일 / public: 정적 자산 / uploads·var: 사용자 업로드 등 런타임 데이터 /
+#   .mega: 마이그레이션 journal / .env*: 시크릿 변경은 수동 재시작.
+# 비우면 모든 변경이 재시작 대상이다(기동 시 경고 1줄).
+WATCH_IGNORE=**/locales/**,**/views/**,**/public/**,**/uploads/**,var/**,logs/**,tmp/**,.mega/**,**/node_modules/**,**/.git/**,**/*.test.js,**/*.spec.js,.env,.env.*,**/templates/**,data/**
+
 # ── 서버 (mega.config.js > server) ───────────────────────────────────────────
 # HTTP listen 포트 — server.port. CLI `--port N` 이 우선(ADR-146).
 PORT=3000

package/sample/crud/.env.example

@@ -20,6 +20,15 @@
 # NODE_ENV=development
 
 
+# ── dev watch ignore (mega.config.js > watch, ADR-220) ───────────────────────
+# `mega start --watch` 의 ignore 목록(콤마 구분 glob) — **여기가 정본**(숨은 코드 디폴트 없음).
+# "런타임이 스스로 쓰거나 재시작 없이 반영되는" 영역을 나열한다. 폴더명을 바꿨으면 이 줄만 고친다.
+#   locales: dev 의 i18n saveMissing 자동 기입(안 빼면 재시작 무한 루프) / views: EJS 는 dev 에서
+#   매 요청 재컴파일 / public: 정적 자산 / uploads·var: 사용자 업로드 등 런타임 데이터 /
+#   .mega: 마이그레이션 journal / .env*: 시크릿 변경은 수동 재시작.
+# 비우면 모든 변경이 재시작 대상이다(기동 시 경고 1줄).
+WATCH_IGNORE=**/locales/**,**/views/**,**/public/**,**/uploads/**,var/**,logs/**,tmp/**,.mega/**,**/node_modules/**,**/.git/**,**/*.test.js,**/*.spec.js,.env,.env.*
+
 # ── 서버 (mega.config.js > server) ───────────────────────────────────────────
 # HTTP listen 포트 — server.port. CLI `--port N` 이 우선(ADR-146).
 PORT=3000

package/sample/crud/apps/main/controllers/upload-controller.js

@@ -8,8 +8,10 @@
  * 시점에 미파싱) 업로드는 `upload-demo.js` 의 fetch + FormData 로 제출한다.
  *
  * 다운로드(GET /demo/upload/file/:name)는 **정적 서빙이 아니라 소스에서 파일을 읽어 전송**한다 — 인증
- * (`webRequireAuth`, 라우트 가드)된 사용자만 받을 수 있다(가드를 떼면 공개로 전환 가능). 파일명은 basename +
- * 디렉터리 내부 검증으로 경로 탐색을 막는다.
+ * (`webRequireAuth`, 라우트 가드)된 사용자만 받을 수 있다(가드를 떼면 공개로 전환 가능). `:name` 은 **실제
+ * 저장 파일명**(코어 `uniquifyFilename` 의 `-<ts36>-<rand8hex>` 접미 포함, ADR-187)이고, 받는 쪽에 제안할
+ * 표시 파일명은 `?as=` 로 따로 받는다(Content-Disposition, RFC 6266/5987 — 한글·공백·괄호 대응). 파일명은
+ * basename + 디렉터리 내부 검증으로 경로 탐색을 막는다.
  *
  * 저장 디렉터리는 **설정(.env `DEMO_UPLOAD_DIR`)** 으로 받는다(미설정 시 `var/uploads`). 상대경로는 프로젝트
  * 루트(`process.cwd()`, views.dir/staticAssets.dir 과 같은 규약 ADR-151) 기준으로 해석한다.
@@ -43,6 +45,21 @@ function uploadDir() {
   return isAbsolute(UPLOAD_DIR_SETTING) ? UPLOAD_DIR_SETTING : join(process.cwd(), UPLOAD_DIR_SETTING)
 }
 
+/**
+ * Content-Disposition: attachment 헤더 값 생성(RFC 6266/5987). 비ASCII 파일명은 quoted-string(`filename=`)에
+ * 실을 수 없으므로 ASCII 폴백과 UTF-8 퍼센트 인코딩(`filename*=`)을 함께 보낸다 — 한글·공백·괄호 파일명 대응.
+ * @param {string} name - 받는 쪽에 제안할 파일명(경로 성분 없음).
+ * @returns {string}
+ */
+function contentDispositionAttachment(name) {
+  // RFC 5987 attr-char 밖 문자는 퍼센트 인코딩 — encodeURIComponent 가 남기는 !'()* 중 '()* 도 추가 인코딩
+  // (MDN encodeRFC5987ValueChars 패턴).
+  const utf8 = encodeURIComponent(name).replace(/['()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)
+  // 구식 filename= 폴백 — 비ASCII·따옴표·백슬래시는 '_' 치환(quoted-string 이 깨지지 않게).
+  const ascii = name.replace(/[^\x20-\x7e]/g, '_').replace(/["\\]/g, '_')
+  return `attachment; filename="${ascii}"; filename*=UTF-8''${utf8}`
+}
+
 export class UploadController {
   /** GET /demo/upload — 업로드 폼 + 최근 업로드 목록 렌더. @param {any} req @param {any} reply @param {any} ctx */
   static async index(req, reply, ctx) {
@@ -61,8 +78,11 @@ export class UploadController {
     // saveUploads 가 MIME 비허용(415)·크기 초과(413)면 throw → 글로벌 핸들러가 에러 envelope 로 응답한다.
     const saved = await req.saveUploads(uploadDir())
     // 저장 경로는 프로젝트 루트 기준 상대경로로 환산(서버 절대경로 노출 회피, 데모에선 위치 확인이 목적).
+    // savedName 은 디스크의 실제 파일명(유일화 접미 포함) — 다운로드 URL 의 키다. filename(표시명)만으론
+    // 디스크 파일을 못 찾는다(코어가 저장 파일명을 uniquifyFilename 으로 유일화, ADR-187).
     const files = saved.map((/** @type {any} */ f) => ({
       filename: f.filename,
+      savedName: basename(f.savedAs),
       bytes: f.bytes,
       mimetype: f.mimetype,
       path: relative(process.cwd(), f.savedAs),
@@ -71,7 +91,7 @@ export class UploadController {
     return { files }
   }
 
-  /** GET /demo/upload/file/:name — 저장된 파일을 소스에서 읽어 전송(인증 필요). @param {any} req @param {any} reply @param {any} ctx */
+  /** GET /demo/upload/file/:name?as=표시명 — 저장된 파일을 소스에서 읽어 전송(인증 필요). @param {any} req @param {any} reply @param {any} ctx */
   static async download(req, reply, ctx) {
     // basename 으로 디렉터리 성분 제거(경로 탐색 1차 차단) — 'a/../b' / '../etc' 류를 단일 파일명으로.
     const safe = basename(String(req.params?.name ?? ''))
@@ -89,9 +109,12 @@ export class UploadController {
       if (err instanceof MegaNotFoundError) throw err
       throw new MegaNotFoundError('upload.not_found', `File '${safe}' not found.`, { cause: err })
     }
-    ctx.log?.debug?.({ file: safe }, 'upload-demo.download')
+    // 받는 쪽 파일명 — 저장명엔 유일화 접미가 붙어 있으므로 ?as= 의 원본 표시명을 우선한다(없으면 저장명).
+    // basename 으로 경로 성분만 제거해 헤더에 쓴다(디스크 접근은 위의 safe 로만).
+    const display = basename(String(req.query?.as ?? '')) || safe
+    ctx.log?.debug?.({ file: safe, display }, 'upload-demo.download')
     // 소스에서 스트리밍 전송(정적 서빙 아님). 스트림 payload 라 Fastify 가 envelope 직렬화를 건너뛴다.
-    reply.header('content-disposition', `attachment; filename="${encodeURIComponent(safe)}"`)
+    reply.header('content-disposition', contentDispositionAttachment(display))
     reply.type(EXT_MIME[extname(safe).toLowerCase()] ?? 'application/octet-stream')
     return reply.send(createReadStream(abs))
   }

package/sample/crud/apps/main/locales/server/en.json

@@ -313,5 +313,16 @@
   "csrf": {
     "invalid_token": "Invalid csrf token",
     "missing_secret": "Missing csrf secret"
-  }
+  },
+  "field_username": "아이디",
+  "field_username_ph": "예: hong123",
+  "field_username_required": "아이디를 입력하세요.",
+  "field_nickname": "별명",
+  "field_nickname_ph": "예: 길동이",
+  "field_nickname_required": "별명을 입력하세요.",
+  "optional": "선택",
+  "field_phone": "전화번호",
+  "field_phone_ph": "예: 010-1234-5678",
+  "col_username": "아이디",
+  "col_nickname": "별명"
 }

package/sample/crud/apps/main/locales/server/ko.json

@@ -313,5 +313,16 @@
   },
   "guide": {
     "not_found": "가이드를 찾을 수 없습니다."
-  }
+  },
+  "field_username": "아이디",
+  "field_username_ph": "예: hong123",
+  "field_username_required": "아이디를 입력하세요.",
+  "field_nickname": "별명",
+  "field_nickname_ph": "예: 길동이",
+  "field_nickname_required": "별명을 입력하세요.",
+  "optional": "선택",
+  "field_phone": "전화번호",
+  "field_phone_ph": "예: 010-1234-5678",
+  "col_username": "아이디",
+  "col_nickname": "별명"
 }

package/sample/crud/apps/main/routes/upload.js

@@ -6,11 +6,30 @@
 import { UploadController } from '../controllers/upload-controller.js'
 import { webRequireAuth } from '../middleware/web-auth.js'
 
+/**
+ * 다운로드 path 파라미터 스키마(ADR-019) — `:name` 은 실제 저장 파일명(유일화 접미 포함, 한글 가능)이라
+ * 형식(빈 값·과대 길이)만 1차 검증한다. 경로 탐색 차단은 컨트롤러의 basename + 디렉터리 내부 검증이 맡는다.
+ */
+const downloadParams = {
+  type: 'object',
+  required: ['name'],
+  properties: { name: { type: 'string', minLength: 1, maxLength: 255 } },
+}
+
+/** 다운로드 query 스키마 — `as` 는 받는 쪽에 제안할 표시 파일명(Content-Disposition 용, 선택). */
+const downloadQuery = {
+  type: 'object',
+  properties: { as: { type: 'string', maxLength: 255 } },
+}
+
 export default (/** @type {any} */ router) => {
   /** @type {{ before: Function[] }} 데모 UI 보호 가드(로그인 필요). */
   const guarded = { before: [webRequireAuth] }
   router.http.get('/demo/upload', UploadController.index, guarded)
   router.http.post('/demo/upload', UploadController.upload, guarded)
   // 다운로드 — 소스에서 파일 읽어 전송(인증 필요). 가드를 떼면 공개 다운로드로 전환된다.
-  router.http.get('/demo/upload/file/:name', UploadController.download, guarded)
+  router.http.get('/demo/upload/file/:name', UploadController.download, {
+    ...guarded,
+    schema: { params: downloadParams, querystring: downloadQuery },
+  })
 }

package/sample/crud/apps/main/services/guide-service.js

@@ -9,7 +9,7 @@ import { MegaNotFoundError } from 'mega-framework/errors'
 
 /**
  * GuideService — /guide 가이드 뷰어 로직(서버사이드 마크다운 렌더). 파일명 `guide-service.js` → 자동 DI
- * 이름 `guide`(ctx.services.guide, ADR-148). 레포 루트의 `docs/guide/*.md` 를 읽어,
+ * 이름 `guide`(ctx.services.guide, ADR-148). 프로젝트의 `docs/guide/*.md` 를 읽어,
  *
  *   1) **목록** — 디렉토리를 scan 해 각 파일의 첫 H1 을 제목으로 뽑는다(인덱스 카드용).
  *   2) **단일 페이지** — 마크다운을 marked 로 HTML 화하고, 코드블록은 highlight.js 로 미리 하이라이트한다.
@@ -18,8 +18,9 @@ import { MegaNotFoundError } from 'mega-framework/errors'
  * 가이드 파일은 정적이라 목록은 프로세스 단위로 캐시한다(개발 중 변경은 재시작으로 갱신).
  */
 
-/** 가이드 마크다운 디렉토리 — 레포 루트의 docs/guide(이 파일 기준 5단계 위). */
-const GUIDE_DIR = fileURLToPath(new URL('../../../../../docs/guide/', import.meta.url))
+/** 가이드 마크다운 디렉토리 — 프로젝트의 docs/guide(이 파일 기준 3단계 위 = 프로젝트 루트). `mega new` 가
+ * sample/crud 트리를 그대로 복사하므로(ADR-179) 스캐폴드된 프로젝트에서도 같은 상대 위치에 존재한다. */
+const GUIDE_DIR = fileURLToPath(new URL('../../../docs/guide/', import.meta.url))
 
 /** 유효 slug 형식 — 소문자·숫자·하이픈만(경로 조작 차단의 1차 게이트). */
 const SLUG_RE = /^[a-z0-9-]+$/

package/sample/crud/apps/main/services/upload-demo-service.js

@@ -17,8 +17,9 @@ export class UploadDemoService extends MegaService {
 
   /**
    * 저장 결과 메타를 최근 이력에 기록한다(파일별 1건). 저장 경로(path)는 프로젝트 루트 기준 상대경로다
-   * (서버 절대경로 비노출 — 데모에선 위치 확인이 목적).
-   * @param {Array<{ filename: string, bytes: number, mimetype: string, path: string }>} saved - 저장 결과 메타.
+   * (서버 절대경로 비노출 — 데모에선 위치 확인이 목적). savedName 은 디스크의 실제 저장 파일명(유일화 접미
+   * 포함) — 다운로드 URL 의 키로 쓴다(표시명 filename 과 다름, ADR-187).
+   * @param {Array<{ filename: string, savedName?: string, bytes: number, mimetype: string, path: string }>} saved - 저장 결과 메타.
    * @returns {Promise<void>}
    */
   async record(saved) {
@@ -28,7 +29,7 @@ export class UploadDemoService extends MegaService {
     for (const f of saved) {
       await redis.lpush(
         UploadDemoService.RECENT_KEY,
-        JSON.stringify({ filename: f.filename, bytes: f.bytes, mimetype: f.mimetype, path: f.path ?? null, at }),
+        JSON.stringify({ filename: f.filename, savedName: f.savedName ?? null, bytes: f.bytes, mimetype: f.mimetype, path: f.path ?? null, at }),
       )
     }
     await redis.ltrim(UploadDemoService.RECENT_KEY, 0, UploadDemoService.RECENT_MAX - 1)
@@ -36,8 +37,8 @@ export class UploadDemoService extends MegaService {
   }
 
   /**
-   * 화면 렌더용 스냅샷 — 최근 업로드 메타 목록.
-   * @returns {Promise<{ recent: Array<{ filename: string, bytes: number, mimetype: string, path: string|null, at: string }> }>}
+   * 화면 렌더용 스냅샷 — 최근 업로드 메타 목록. savedName 도입 전 이력엔 필드가 없을 수 있다(뷰가 path 로 보완).
+   * @returns {Promise<{ recent: Array<{ filename: string, savedName?: string|null, bytes: number, mimetype: string, path: string|null, at: string }> }>}
    */
   async snapshot() {
     const redis = this.ctx.cache('demo').native

package/sample/crud/apps/main/views/upload/index.ejs

@@ -2,6 +2,9 @@
 <%
   function fmt(d) { return new Date(d).toLocaleString('ko-KR', { hour12: false, timeZone: 'Asia/Seoul' }) }
   function kb(b) { return (Number(b) / 1024).toFixed(1) + ' KB' }
+  // 다운로드 키 — 디스크의 실제 저장 파일명(유일화 접미 포함). savedName 도입 전 이력은 저장 경로의
+  // basename 으로 보완한다(표시명으론 디스크 파일을 못 찾음).
+  function dlName(e) { return e.savedName || String(e.path || e.filename).split(/[\\/]/).pop() }
 %>
 
 <div class="mb-4">
@@ -60,7 +63,7 @@
                   <tr>
                     <td class="font-monospace small"><%= fmt(e.at) %></td>
                     <td class="small text-break">
-                      <a href="/demo/upload/file/<%= encodeURIComponent(e.filename) %>"><%= e.filename %></a>
+                      <a href="/demo/upload/file/<%= encodeURIComponent(dlName(e)) %>?as=<%= encodeURIComponent(e.filename) %>"><%= e.filename %></a>
                     </td>
                     <td class="font-monospace small text-break"><%= e.path || '—' %></td>
                     <td><span class="badge text-bg-light"><code><%= e.mimetype %></code></span></td>