@gaonjs/cli 0.43.0 → 0.47.0

package/dist/templates/project/pnpm-workspace.yaml.tpl

@@ -1,5 +1,5 @@
 # pnpm workspace — 앱은 apps/*, 도메인은 domain/, 공용은 shared/ 아래에 둔다.
-# 이 관례는 CLAUDE.md §2 · v0.15 §3.2 를 따른다(앱과 domain 은 별도 폴더).
+# 이 관례는 CLAUDE.md §2 · v0.17 §3.2 를 따른다(앱과 domain 은 별도 폴더).
 packages:
   - "packages/*"
 

package/dist/templates/project/vite.config.ts.tpl

@@ -1,4 +1,4 @@
-// vite.config.ts — 프론트엔드 빌드/개발 서버 설정 (v0.16 §6.4).
+// vite.config.ts — 프론트엔드 빌드/개발 서버 설정 (v0.17 §6.4).
 //
 // The One Way: gaon dev 가 Vite 를 middlewareMode 로 붙여 Fastify 한 포트로
 // 서빙한다(§CLAUDE.md 6 · 이 파일의 server 옵션은 그때 재정의된다).

package/dist/work.d.ts

@@ -1,3 +1,4 @@
+import { type WorkEvent } from '@gaonjs/async';
 export interface WorkCommandOptions {
     readonly json?: boolean;
     /** NATS 접속지. 생략 시 NATS_URL(그다음 하위호환 GAON_NATS_URL), 기본(4222). */
@@ -12,12 +13,32 @@ export interface WorkCommandOptions {
     readonly ackWaitMs?: number;
     /** graceful drain 상한(ms). 생략 시 GAON_WORKER_DRAIN_MS. */
     readonly drainTimeoutMs?: number;
+    /** 발행 완료 아웃박스 행 보존(ms · 0=purge 비활성). 생략 시 GAON_OUTBOX_RETENTION_MS(결정 312). */
+    readonly outboxRetentionMs?: number;
+    /** 아웃박스 purge 최소 간격(ms). 생략 시 GAON_OUTBOX_PURGE_INTERVAL_MS(결정 312). */
+    readonly outboxPurgeIntervalMs?: number;
+    /** 아웃박스 릴레이 폴링 주기(ms). 생략 시 GAON_OUTBOX_RELAY_POLL_MS(결정 312). */
+    readonly relayPollMs?: number;
     /** 시그널 등록·해제(테스트 주입). 기본 process. */
     readonly signals?: {
         on(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
         off(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
     };
 }
+/**
+ * 아웃박스 릴레이 튜닝을 env 에서 읽는다(결정 312 · GAON_WORKER_* 와 대칭).
+ * 이전엔 runWork() 프로그래매틱 옵션으로만 존재해 정본 운영 경로(`gaon work`)에서
+ * 보존 기간·purge 간격·폴링 주기를 조정할 방법이 없었다. env 미설정·비정상 값은
+ * undefined → runWork 기본(보존 7일 · purge 1시간 · 폴 1초 · 결정 78)이 그대로다.
+ */
+export declare function outboxTuningFromEnv(env?: Record<string, string | undefined>): {
+    outboxRetentionMs?: number;
+    outboxPurgeIntervalMs?: number;
+    relayPollMs?: number;
+};
+/** WorkEvent → 사람용 한 줄(없으면 undefined). 결정 306·308: 조용한 실패(릴레이
+ * 오류·리스너 폐기·워커 인프라 오류)가 기본(human) 모드에서 0 신호이던 갭을 닫는다. */
+export declare function emitHuman(e: WorkEvent): string | undefined;
 /**
  * 워커를 띄우고 시그널까지 살려 둔다. 반환 프라미스는 graceful 종료 시 resolve.
  */

package/dist/work.js

@@ -29,7 +29,29 @@ function envInt(name) {
     const n = Number(raw);
     return Number.isFinite(n) ? n : undefined;
 }
-function emitHuman(e) {
+/**
+ * 아웃박스 릴레이 튜닝을 env 에서 읽는다(결정 312 · GAON_WORKER_* 와 대칭).
+ * 이전엔 runWork() 프로그래매틱 옵션으로만 존재해 정본 운영 경로(`gaon work`)에서
+ * 보존 기간·purge 간격·폴링 주기를 조정할 방법이 없었다. env 미설정·비정상 값은
+ * undefined → runWork 기본(보존 7일 · purge 1시간 · 폴 1초 · 결정 78)이 그대로다.
+ */
+export function outboxTuningFromEnv(env = process.env) {
+    const readInt = (name) => {
+        const raw = env[name];
+        if (raw == null || raw === '')
+            return undefined;
+        const n = Number(raw);
+        return Number.isFinite(n) ? n : undefined;
+    };
+    return {
+        outboxRetentionMs: readInt('GAON_OUTBOX_RETENTION_MS'),
+        outboxPurgeIntervalMs: readInt('GAON_OUTBOX_PURGE_INTERVAL_MS'),
+        relayPollMs: readInt('GAON_OUTBOX_RELAY_POLL_MS'),
+    };
+}
+/** WorkEvent → 사람용 한 줄(없으면 undefined). 결정 306·308: 조용한 실패(릴레이
+ * 오류·리스너 폐기·워커 인프라 오류)가 기본(human) 모드에서 0 신호이던 갭을 닫는다. */
+export function emitHuman(e) {
     switch (e.kind) {
         case 'ready':
             return `  gaon work · 준비 — 잡 ${e.jobs} · 리스너 ${e.listeners} · 스케줄 ${e.scheduled}`;
@@ -38,13 +60,30 @@ function emitHuman(e) {
                 return e.event.leader ? '  ▶ 스케줄러 리더 — 틱 발행 시작' : '  · 스케줄러 대기(standby)';
             if (e.event.kind === 'fired')
                 return `  ⏰ 스케줄 발행 — ${e.event.label}`;
+            if (e.event.kind === 'error')
+                return `  ⚠ 스케줄러 오류 — ${e.event.error}`;
             return undefined;
         case 'worker':
             if (e.event.kind === 'dead')
                 return `  ✗ 잡 DLQ — ${e.event.job} (${e.event.error})`;
+            // 결정 308: 재시도·인프라 오류(재적재/DLQ 발행 실패 nak · 결정 258)도 신호한다.
+            if (e.event.kind === 'retrying')
+                return `  ↻ 잡 재시도 — ${e.event.job} (시도 ${e.event.attempt} · ${e.event.delayMs}ms 뒤)`;
+            if (e.event.kind === 'error')
+                return `  ⚠ 워커 오류 — ${e.event.error}`;
+            return undefined;
+        case 'listener':
+            // 결정 308: maxDeliver 소진 = 이벤트 영구 폐기(DLQ 없음 · agents/async.md §3) — 반드시 신호.
+            if (e.event.kind === 'dropped')
+                return `  ✗ 이벤트 폐기 — ${e.event.listener} ← ${e.event.event} (재전달 소진: ${e.event.error})`;
+            if (e.event.kind === 'error')
+                return `  ⚠ 리스너 오류 — ${e.event.error}`;
             return undefined;
         case 'relay':
             return `  ↪ 아웃박스 릴레이 — ${e.count}건 발행`;
+        case 'relay-error':
+            // 결정 306: 아웃박스 발행 실패(행 격리·재시도 유지)를 조용히 삼키지 않는다.
+            return `  ⚠ 아웃박스 릴레이 오류 — ${e.error}`;
         case 'purge':
             return `  🧹 아웃박스 정리 — ${e.count}건 삭제(보존 기간 초과)`;
         default:
@@ -99,6 +138,7 @@ export async function runWorkCommand(opts = {}) {
             registerConnection('main', createDb(cfg), cfg.adapter);
         }
         const db = hasConnection('main') ? getConnection('main') : undefined;
+        const outboxEnv = outboxTuningFromEnv();
         const domain = await loadDomain(root);
         // 로드된 도메인 자산 요약(파일=등록 관측용). 잡·리스너·메일 수를 노출한다.
         if (json) {
@@ -120,6 +160,10 @@ export async function runWorkCommand(opts = {}) {
             concurrency: opts.concurrency ?? envInt('GAON_WORKER_CONCURRENCY'),
             ackWaitMs: opts.ackWaitMs ?? envInt('GAON_WORKER_ACK_WAIT_MS'),
             drainTimeoutMs: opts.drainTimeoutMs ?? envInt('GAON_WORKER_DRAIN_MS'),
+            // 아웃박스 릴레이 튜닝: 옵션 > GAON_OUTBOX_* env > runWork 기본(결정 78·312).
+            outboxRetentionMs: opts.outboxRetentionMs ?? outboxEnv.outboxRetentionMs,
+            outboxPurgeIntervalMs: opts.outboxPurgeIntervalMs ?? outboxEnv.outboxPurgeIntervalMs,
+            relayPollMs: opts.relayPollMs ?? outboxEnv.relayPollMs,
             onEvent: emit,
         });
     }

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.43.0",
+  "version": "0.47.0",
   "description": "Gaon CLI — 스캐폴딩·제너레이터·마이그레이션·dev/serve/work/hub·doctor·check (bin: gaon)",
   "type": "module",
   "license": "MIT",
   "homepage": "https://gaonjs.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.nyx-zone.com/gaon/framework.git",
+    "directory": "packages/cli"
+  },
   "engines": {
     "node": ">=22"
   },
@@ -27,15 +32,15 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
-    "@gaonjs/async": "0.15.3",
-    "@gaonjs/config": "0.19.0",
-    "@gaonjs/data": "0.21.0",
+    "@gaonjs/config": "0.20.0",
     "@gaonjs/core": "0.2.4",
+    "@gaonjs/async": "0.16.0",
     "@gaonjs/i18n": "0.2.4",
-    "@gaonjs/web": "0.21.0",
-    "@gaonjs/mail": "0.3.3"
+    "@gaonjs/mail": "0.3.3",
+    "@gaonjs/data": "0.22.0",
+    "@gaonjs/web": "0.24.1"
   },
   "scripts": {
-    "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""
+    "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"const fs=require('fs');fs.cpSync('src/templates','dist/templates',{recursive:true,filter:(s)=>!s.endsWith('.ts')});fs.rmSync('dist/templates/index.ts',{force:true})\""
   }
 }

package/dist/templates/index.ts

@@ -1,109 +0,0 @@
-// @gaonjs/cli · templates/index.ts — 프로젝트 스캐폴드 템플릿 로더 (M9-F).
-//
-// `gaon new <name>` 이 소비하는 파일 트리. 소스 트리(src/templates/project/*)
-// 를 재귀 스캔해 각 `.tpl` 파일의 최종 경로와 렌더된 내용을 반환한다.
-// 렌더는 `{{TOKEN}}` 리터럴 replaceAll — Vue 의 `{{ }}` 보간과 겹치지 않는
-// 고정 리터럴이라 정규식 없이 안전하다(generate.ts 와 동일 관례).
-//
-// 폴더는 관례상 유지되어야 하지만 git 이 빈 폴더를 추적하지 않으므로
-// `.gitkeep.tpl` 을 두어 실 파일 `.gitkeep` 으로 렌더한다. 최종 경로는
-// `.tpl` 접미사를 벗긴 값이다.
-
-import { readFileSync, readdirSync } from 'node:fs'
-import { dirname, join, posix, relative, sep } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-/** 생성할 파일 하나 — path 는 프로젝트 루트 기준 상대 경로(POSIX). */
-export interface ProjectFile {
-  readonly path: string
-  readonly contents: string
-}
-
-/** 템플릿 렌더 시 치환되는 토큰 값. */
-export interface ProjectTemplateTokens {
-  readonly projectName: string
-  readonly gaonjsVersion: string
-  /**
-   * package.json 의 `packageManager` 필드(corepack 핀 · 예 `pnpm@10.27.0`).
-   * 미지정 시 blessed 기본 pnpm. 선택한 pm 에 맞춰 채운다(결정 169).
-   */
-  readonly packageManager?: string
-}
-
-const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), 'project')
-
-/**
- * pm 별 `packageManager` 핀(corepack 형식 `<pm>@<x.y.z>`). 선택한 pm 을
- * 그대로 적어 corepack enforcement 가 install 을 막지 않게 한다(결정 169 ·
- * 12차 실사용 yarn 파손). 정본 버전 근거:
- *  · pnpm@10.27.0 — blessed 툴체인(Dockerfile corepack·CI)과 정합.
- *  · yarn@1.22.22 — yarn **classic** 최종 안정판. berry(2·4.x)는 `.yarnrc.yml`
- *    없이 기본 PnP 라 node_modules 를 읽는 vite·gaon serve 를 깨므로 배제.
- *  · npm@10.9.9 — engines.node≥22(Node 22 LTS) 동봉 npm 라인의 tip.
- */
-export const PACKAGE_MANAGER_PINS: Readonly<Record<'pnpm' | 'npm' | 'yarn', string>> = {
-  pnpm: 'pnpm@10.27.0',
-  npm: 'npm@10.9.9',
-  yarn: 'yarn@1.22.22',
-}
-
-/** blessed 기본(pm 미선택 시). */
-export const DEFAULT_PACKAGE_MANAGER = PACKAGE_MANAGER_PINS.pnpm
-
-/** 템플릿 문자열의 {{TOKEN}} 을 치환한다. 알 수 없는 토큰은 그대로 둔다. */
-export function renderTemplate(raw: string, tokens: ProjectTemplateTokens): string {
-  return raw
-    .replaceAll('{{PROJECT_NAME}}', tokens.projectName)
-    .replaceAll('{{GAONJS_VERSION}}', tokens.gaonjsVersion)
-    .replaceAll('{{PACKAGE_MANAGER}}', tokens.packageManager ?? DEFAULT_PACKAGE_MANAGER)
-}
-
-/** 템플릿 폴더를 재귀 스캔해 파일 목록을 만든다(POSIX 경로 · 정렬). */
-export function listTemplateFiles(root: string = TEMPLATE_DIR): string[] {
-  const out: string[] = []
-  const walk = (dir: string): void => {
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      const abs = join(dir, entry.name)
-      if (entry.isDirectory()) {
-        walk(abs)
-        continue
-      }
-      if (!entry.isFile()) continue
-      out.push(abs)
-    }
-  }
-  walk(root)
-  return out.sort()
-}
-
-/**
- * 스캐폴드 파일 전체를 렌더링해 반환한다.
- * `.tpl` 접미사는 벗기고, `{{PROJECT_NAME}}`·`{{GAONJS_VERSION}}` 을 치환한다.
- */
-export function renderProjectFiles(tokens: ProjectTemplateTokens): ProjectFile[] {
-  const paths = listTemplateFiles()
-  return paths.map((abs) => {
-    const rel = relative(TEMPLATE_DIR, abs).split(sep).join(posix.sep)
-    const outPath = rel.endsWith('.tpl') ? rel.slice(0, -'.tpl'.length) : rel
-    const raw = readFileSync(abs, 'utf8')
-    return { path: outPath, contents: renderTemplate(raw, tokens) }
-  })
-}
-
-/** 테스트·검증용 — 템플릿 폴더의 절대 경로. */
-export function templateDir(): string {
-  return TEMPLATE_DIR
-}
-
-/** 렌더링된 내용에 미치환 토큰이 남아 있는지 검사(회귀 방지). */
-export function findUnresolvedTokens(contents: string): string[] {
-  const re = /\{\{([A-Z_][A-Z0-9_]*)\}\}/g
-  const found = new Set<string>()
-  for (const m of contents.matchAll(re)) {
-    // Vue 템플릿의 {{ prop }} (소문자·공백 시작) 은 제외 — 위 정규식이 대문자만
-    // 잡으므로 자연스럽게 걸러진다. 남으면 진짜 미치환.
-    found.add(m[1]!)
-  }
-  return [...found].sort()
-}
-