@gaonjs/cli 0.52.0 → 0.55.0

package/dist/i18n-config.js

@@ -15,23 +15,64 @@ export function analyzeConfigI18n(source) {
     let declared = false;
     let dir;
     let fallbackLng;
+    let supportedLngs;
+    const unresolved = new Set();
+    // 결정 412: `as`·`satisfies` 래핑을 벗긴다 — defineConfig({...} satisfies GaonConfig)
+    // 는 실사용 형태인데 종전엔 객체 리터럴이 아니라고 보고 i18n 선언 자체를 놓쳤다.
+    const unwrap = (node) => {
+        let e = node;
+        while (ts.isParenthesizedExpression(e) || ts.isAsExpression(e) || ts.isSatisfiesExpression(e)) {
+            e = e.expression;
+        }
+        return e;
+    };
+    // 문자열 리터럴 + 치환 없는 템플릿 리터럴(`translations`)을 함께 읽는다 — 개발자
+    // 눈에는 똑같은 리터럴인데 종전엔 템플릿만 무소음으로 빠졌다(결정 412).
+    const literalText = (e) => {
+        const n = unwrap(e);
+        if (ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n))
+            return n.text;
+        return undefined;
+    };
     // i18n 초기화식에서 객체 리터럴을 찾는다 — 삼항·??·&&·괄호는 양변을 훑는다
     // (connections.ts 와 동일 규약 · env 조건부 블록 대응). 두 분기가 서로 다른
     // 리터럴을 주는 병리적 케이스는 먼저 읽힌 값을 쓴다(실사용 형태 아님).
-    const collect = (node) => {
-        if (ts.isParenthesizedExpression(node))
-            return collect(node.expression);
+    const collect = (raw) => {
+        const node = unwrap(raw);
         if (ts.isObjectLiteralExpression(node)) {
             for (const p of node.properties) {
+                // 결정 412: shorthand(`{ i18n }`)·스프레드는 값을 여기서 알 수 없다 — 조용히
+                // 넘기지 않고 미해석으로 표시한다.
+                if (ts.isShorthandPropertyAssignment(p) || ts.isSpreadAssignment(p)) {
+                    unresolved.add('dir');
+                    unresolved.add('fallbackLng');
+                    continue;
+                }
                 if (!ts.isPropertyAssignment(p))
                     continue;
                 const name = propNameText(p.name);
-                if (name === 'dir' && ts.isStringLiteral(p.initializer) && dir === undefined) {
-                    dir = p.initializer.text;
+                // 결정 413: supportedLngs 는 리터럴 배열일 때만 읽는다(check 정적 미러용).
+                if (name === 'supportedLngs' && supportedLngs === undefined) {
+                    const arr = unwrap(p.initializer);
+                    if (ts.isArrayLiteralExpression(arr)) {
+                        const items = arr.elements.map((el) => literalText(el));
+                        if (items.every((v) => v !== undefined))
+                            supportedLngs = items;
+                    }
+                    continue;
                 }
-                if (name === 'fallbackLng' && ts.isStringLiteral(p.initializer) && fallbackLng === undefined) {
-                    fallbackLng = p.initializer.text;
+                if (name !== 'dir' && name !== 'fallbackLng')
+                    continue;
+                const text = literalText(p.initializer);
+                if (text === undefined) {
+                    // 변수 참조·env 표현식 등 — 런타임 실값과 갈라지는 지점.
+                    unresolved.add(name);
+                    continue;
                 }
+                if (name === 'dir' && dir === undefined)
+                    dir = text;
+                if (name === 'fallbackLng' && fallbackLng === undefined)
+                    fallbackLng = text;
             }
             return;
         }
@@ -53,8 +94,16 @@ export function analyzeConfigI18n(source) {
     const visit = (node) => {
         if (ts.isCallExpression(node) && isDefineConfig(node.expression)) {
             const arg = node.arguments[0];
-            if (arg && ts.isObjectLiteralExpression(arg)) {
-                for (const p of arg.properties) {
+            const obj = arg ? unwrap(arg) : undefined;
+            if (obj && ts.isObjectLiteralExpression(obj)) {
+                for (const p of obj.properties) {
+                    if (ts.isShorthandPropertyAssignment(p) && p.name.text === 'i18n') {
+                        // `defineConfig({ i18n })` — 선언은 확실하나 값은 정적으로 못 읽는다.
+                        declared = true;
+                        unresolved.add('dir');
+                        unresolved.add('fallbackLng');
+                        continue;
+                    }
                     if (ts.isPropertyAssignment(p) && propNameText(p.name) === 'i18n') {
                         declared = true;
                         collect(p.initializer);
@@ -65,20 +114,46 @@ export function analyzeConfigI18n(source) {
         ts.forEachChild(node, visit);
     };
     visit(sf);
-    return { declared, dir, fallbackLng };
+    // 읽힌 키는 미해석 목록에서 뺀다(한 분기만 리터럴인 경우 값이 있으면 그 값을 쓴다).
+    if (dir !== undefined)
+        unresolved.delete('dir');
+    if (fallbackLng !== undefined)
+        unresolved.delete('fallbackLng');
+    return { declared, dir, fallbackLng, supportedLngs, unresolved: [...unresolved] };
 }
 /** cwd 의 gaon.config.ts 를 읽어 i18n 블록을 분석한다. 파일이 없으면 미선언. */
 export function analyzeProjectI18n(cwd) {
     const configPath = join(cwd, 'gaon.config.ts');
     if (!existsSync(configPath))
-        return { declared: false };
+        return { declared: false, unresolved: [] };
     try {
         return analyzeConfigI18n(readFileSync(configPath, 'utf8'));
     }
     catch {
-        return { declared: false };
+        return { declared: false, unresolved: [] };
     }
 }
+/**
+ * 결정 412: 카탈로그 디렉터리의 절대 경로. `dir` 이 절대 경로면 그대로 쓴다 —
+ * wire(런타임)는 이미 그렇게 해석하는데 CLI 축만 무조건 join 해서
+ * `join('/proj','/var/locales')` = `/proj/var/locales` 로 조용히 빗나갔다.
+ */
+export function resolveLocalesDir(cwd, dir) {
+    const d = dir ?? 'locales';
+    return d.startsWith('/') ? d : join(cwd, d);
+}
+/**
+ * 결정 412: 정적으로 못 읽은 i18n 키를 한 줄 경고로 알린다(무신호 금지). 런타임은
+ * 실값을, 타입 축·doctor 는 폴백을 쓰므로 messages.d.ts 가 엉뚱한 카탈로그를 보거나
+ * 아예 안 생길 수 있다 — 어느 형태로 바꾸면 되는지까지 쓴다(§7.5.3).
+ */
+export function warnUnresolvedI18n(analysis, write) {
+    if (analysis.unresolved.length === 0)
+        return;
+    write(`  ! gaon.config.ts 의 i18n ${analysis.unresolved.join('·')} 을(를) 정적으로 읽지 못했습니다 — ` +
+        `타입 축(.gaon/messages.d.ts)과 doctor 는 기본값(dir='locales' · 기준=정렬 첫 로케일)을 씁니다.\n` +
+        `    → 문자열 리터럴로 직접 쓰면 정확히 반영됩니다: i18n: { dir: 'locales', fallbackLng: 'ko' }\n`);
+}
 function isDefineConfig(e) {
     if (ts.isIdentifier(e) && e.text === 'defineConfig')
         return true;

package/dist/index.js

@@ -109,13 +109,15 @@ function renderHelp(version = VERSION) {
         "    gaon gen           .gaon 타입 브리지 + api() 런타임 매니페스트만 재생성 (서버·검사 없이 · build 전제 · --json)",
         "    gaon build         멀티 앱 프론트 프로덕션 빌드 (gaon gen + apps/* 순회 · 앱별 dist/<앱>·base=/<앱>/ · --json)",
         "    gaon console       프로젝트 컨텍스트 REPL (--no-config)",
-        "    gaon test          테스트 러너 (테스트 DB <db>_test 자동 생성·마이그레이션 후 vitest · --scope unit|integration|all · -- vitest 인자)",
+        "    gaon test          테스트 러너 (테스트 DB <db>_test 자동 생성·마이그레이션 후 vitest · --scope unit|integration|all)",
+        "    gaon test -- <인자>       `--` 뒤는 vitest 로 그대로 전달 (gaon 이 안 가로챔 · 예: gaon test -- --json --reporter=json)",
         `    gaon doctor        정적 검사 (${ALL_RULES.length} 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트·Link>Button 중첩·seal 클라 배선·보안 역전·§4.5 관계·import.meta.env·로케일 커버리지·render return 누락)`,
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon doctor --fix                         기계 정정 가능한 위반 계획(dry-run · v0.16 §7.5.3)",
         "    gaon doctor --fix --yes                   실제 편집 적용(원본은 .bak-<타임스탬프> 로 자동 백업)",
-        "    gaon g auth        인증 스캐폴드 생성 (회원가입·로그인·세션·보호 라우트 · --jwt --app <api> = API 앱 토큰 변형)",
+        "    gaon g auth        인증 스캐폴드 생성 (회원가입·로그인·세션·보호 라우트 · --jwt --app <api> = API 앱 토큰 변형 · --public = 비-web 앱 공개 가입)",
+        "    gaon g ui-kit      UI 킷 스캐폴드 (Button·Input 등 원자 프리미티브 · --app <이름>)",
         "    gaon g controller <name>   컨트롤러 스캐폴드 (Rails 관례 · 페이지+JSON 액션)",
         "    gaon g model <Name>        모델 스캐폴드 (스키마+모델 · E-4 컬럼 예시)",
         "    gaon g page <Path/Name>    Vue 페이지 (Inertia SPA · pageProps 브리지)",
@@ -152,14 +154,29 @@ export function parseDoctorChecks(argv) {
     // 전체 검사로 되돌아가던 표류를 근본 차단한다(결정 168).
     const isKnown = (s) => ALL_RULES.includes(s);
     const out = [];
+    const unknown = [];
     for (const a of argv) {
         if (a.startsWith("--check=")) {
             for (const nm of a.slice("--check=".length).split(",")) {
-                if (isKnown(nm) && !out.includes(nm))
-                    out.push(nm);
+                if (isKnown(nm)) {
+                    if (!out.includes(nm))
+                        out.push(nm);
+                }
+                else if (nm !== "" && !unknown.includes(nm)) {
+                    unknown.push(nm);
+                }
             }
         }
     }
+    // 결정 411: 모르는 이름은 여전히 무시하되(안전 방향 — 전체 검사로 넓어짐) **조용히**
+    // 넘기지 않는다. 오타 하나가 "그 검사만 돌렸다" 는 착각으로 이어지고, 전부 오타면
+    // 28종 전체가 돌아가 선택 실행 의도가 통째로 사라진다.
+    if (unknown.length > 0) {
+        process.stderr.write(`  ! 알 수 없는 검사 이름 무시: ${unknown.join(", ")}\n` +
+            `    → 지원 이름은 gaon doctor --json 의 rule 값 또는 gaon help 참고` +
+            (out.length === 0 ? " (인정된 이름이 없어 전체 검사를 실행합니다)" : "") +
+            "\n");
+    }
     return out.length ? out : undefined;
 }
 /**
@@ -225,6 +242,20 @@ export function parseDbArgs(sub, argv) {
     const dbIdx = argv.indexOf("--db");
     const cfgIdx = argv.indexOf("--config");
     const valueFlags = new Set(["--db", "--config"]);
+    // 결정 404: 값 플래그의 **값 부재**도 fail-loud. `gaon db migrate --db`(값 없이 끝)는
+    // db=undefined 가 돼 "커넥션 하나만" 이던 의도가 조용히 **전 커넥션 적용**으로 확장됐다
+    // (결정 139 순회 기본값과 결합해 파괴 반경이 커진다). readPortFlag(결정 240)와 같은 규약.
+    for (const f of valueFlags) {
+        const i = argv.indexOf(f);
+        if (i < 0)
+            continue;
+        const v = argv[i + 1];
+        if (v === undefined || v.startsWith("-")) {
+            throw new Error(`gaon db ${sub}: ${f} 값이 없습니다.\n` +
+                `  → 예: gaon db ${sub} ${f} ${f === "--db" ? "main" : "gaon.config.ts"}\n` +
+                `  → 값 없이 두면 ${f === "--db" ? "전 커넥션에 적용" : "기본 설정 파일 사용"}으로 조용히 넓어져 멈춥니다.`);
+        }
+    }
     // 결정 358: db 는 파괴 방향 오동작이 가능한 명령군이라 미지 플래그를 조용히
     // 무시하지 않는다 — `--dryrun`(오타)이 무시되면 dry-run 의도가 **실제 마이그레이션
     // 적용**으로 반전된다(결정 267 down-위치 문제와 동형). 인정 집합 밖 `--*` 는 throw.
@@ -248,6 +279,19 @@ export function parseDbArgs(sub, argv) {
         }
         positionals.push(a);
     }
+    // 결정 404: 미지 **위치 인자**도 막는다. 종전엔 positionals 가 'down' 판정에만 쓰이고
+    // 나머지는 버려져서 `gaon db migrate donw`(오타)·`rollback`(타 프레임웍 관례)이 무경고로
+    // **정방향 migrate 실 적용**으로 반전됐다 — 결정 358 이 플래그에서 막은 것과 같은 파괴
+    // 방향인데 위치 인자만 뚫려 있었다.
+    const allowedPositionals = sub === "migrate" ? ["down"] : [];
+    const unknown = positionals.find((p) => !allowedPositionals.includes(p));
+    if (unknown !== undefined) {
+        throw new Error(`gaon db ${sub}: 알 수 없는 인자 '${unknown}'.\n` +
+            (sub === "migrate"
+                ? `  → 지원 인자: down(롤백) 하나뿐입니다. 예: gaon db migrate down\n`
+                : `  → gaon db ${sub} 는 위치 인자를 받지 않습니다.\n`) +
+            `  → 오타가 조용히 무시되면 의도와 반대로(예: 롤백 대신 정방향 적용) 실행될 수 있어 멈춥니다.`);
+    }
     return {
         json: argv.includes("--json"),
         db: dbIdx >= 0 ? argv[dbIdx + 1] : undefined,
@@ -372,9 +416,17 @@ export function runCli(argv, opts = {}) {
         const knownSteps = ["typecheck", "vue-tsc", "build", "doctor"];
         const onlyIdx = argv.indexOf("--only");
         const onlyRaw = onlyIdx >= 0 ? argv[onlyIdx + 1] : undefined;
-        const only = onlyRaw && knownSteps.includes(onlyRaw)
-            ? onlyRaw
-            : undefined;
+        // 결정 411: `--only` 오타를 조용히 전체 실행으로 폴백하지 않는다 — "typecheck 만
+        // 돌렸다" 는 착각으로 CI 시간이 늘거나(안전 방향이라 더 안 보인다), 반대로
+        // 단일 단계만 돌린 줄 알고 넘어간다. 값 부재도 같이 막는다(--port 규약 · 결정 240).
+        if (onlyIdx >= 0 && (onlyRaw === undefined || !knownSteps.includes(onlyRaw))) {
+            process.stderr.write(`  ✗ gaon check: --only 값이 ${onlyRaw === undefined ? "없습니다" : `잘못됐습니다('${onlyRaw}')`}.\n` +
+                `    → 지원 단계: ${knownSteps.join(" · ")}\n` +
+                `    → 예: gaon check --only typecheck\n`);
+            process.exitCode = 2;
+            return;
+        }
+        const only = onlyRaw !== undefined ? onlyRaw : undefined;
         void runCheckCommand({
             json: argv.includes("--json"),
             only,
@@ -437,9 +489,14 @@ export function runCli(argv, opts = {}) {
             // --fix (dry-run): errors > 0 이면 1 · errors 0 이어도 **계획이 있으면 1**
             //              (고칠 게 있다는 신호 — 이전엔 warning-only 계획이 0 으로 삼켜짐).
             // 기본: errors > 0 이면 1.
+            // 결정 410: `--fix --yes` 인데 **적용에 성공한 게 하나도 없으면** 비-0.
+            // 종전엔 잔여 errors 만 봐서, 위반이 warning 레벨이고 fixer 가 전부 실패하면
+            // (fixer 예외·대상 파일 선점 등) "고친 것 0" 인데 exit 0 이라 자동화가
+            // "고쳐졌다" 로 오판했다 — 시도했는데 아무것도 못 고친 건 성공이 아니다.
             const fix = result.fix;
             const dryPlans = fix !== undefined && !fix.applied && fix.outcomes.length > 0;
-            process.exitCode = result.errors.length > 0 || dryPlans ? 1 : 0;
+            const nothingApplied = fix !== undefined && fix.applied && fix.outcomes.length > 0 && !fix.outcomes.some((o) => o.applied);
+            process.exitCode = result.errors.length > 0 || dryPlans || nothingApplied ? 1 : 0;
         })
             .catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
@@ -505,21 +562,33 @@ export function runCli(argv, opts = {}) {
     if (argv[0] === "db") {
         const sub = argv[1];
         const known = ["diff", "migrate", "reset", "seed", "status"];
+        // 결정 411: --json 모드면 실패 사유도 **구조화**해서 낸다 — runDbCommand 는 이미
+        // JSON 에러를 방출하는데(commands/db.ts) 라우팅 단계 실패만 텍스트라 자동화가
+        // 사유를 못 받았다(비대칭).
+        const dbJson = argv.includes("--json");
+        const failDb = (message) => {
+            if (dbJson) {
+                process.stdout.write(JSON.stringify({ ok: false, kind: "usage", command: "db", message }) + "\n");
+            }
+            else {
+                process.stderr.write(`  ✗ ${message}\n`);
+            }
+            process.exitCode = 1;
+        };
         if (!sub || !known.includes(sub)) {
-            process.stderr.write(`  ✗ 알 수 없는 db 서브커맨드: ${sub ?? "(없음)"}\n` +
+            failDb(`알 수 없는 db 서브커맨드: ${sub ?? "(없음)"}\n` +
                 `  → 지원: gaon db diff | migrate | reset | seed | status\n` +
-                `  → 옵션: --json · --db <키>(생략 = 전 커넥션 순회) · --config <path> · --yes · --dry-run\n`);
-            process.exitCode = 1;
+                `  → 옵션: --json · --db <키>(생략 = 전 커넥션 순회) · --config <path> · --yes · --dry-run`);
             return;
         }
-        // 결정 358: 미지 플래그는 파싱 경계에서 fail-loud(오타 dry-run 이 실 적용되는 반전 방지).
+        // 결정 358·404: 미지 플래그·미지 위치 인자·값 부재는 파싱 경계에서 fail-loud
+        // (오타 dry-run 이 실 적용되는 반전 방지).
         let dbOpts;
         try {
             dbOpts = parseDbArgs(sub, argv);
         }
         catch (err) {
-            process.stderr.write(`  ✗ ${err instanceof Error ? err.message : String(err)}\n`);
-            process.exitCode = 1;
+            failDb(err instanceof Error ? err.message : String(err));
             return;
         }
         void runDbCommand(sub, dbOpts)
@@ -659,14 +728,27 @@ export function runCli(argv, opts = {}) {
     // `gaon test [--scope unit|integration|all] [-- vitest 인자]` — 테스트 러너(M9-G).
     if (argv[0] === "test") {
         const rest = argv.slice(1);
-        const scopeIdx = rest.indexOf("--scope");
-        const scopeRaw = scopeIdx >= 0 ? rest[scopeIdx + 1] : undefined;
-        const scope = scopeRaw === "unit" || scopeRaw === "integration" || scopeRaw === "all"
-            ? scopeRaw
-            : undefined;
+        // 결정 411: `--` 뒤는 **전부 vitest 몫**이다. 종전엔 gaon 이 위치와 무관하게
+        // --json·--scope 를 가로채 `gaon test -- --json`(vitest 자체 JSON 리포터)이
+        // 불가능했다 — 탈출구를 연다(help 에 적힌 계약과 코드를 일치시킨다).
+        const sepIdx = rest.indexOf("--");
+        const own = sepIdx >= 0 ? rest.slice(0, sepIdx) : rest;
+        const forwarded = sepIdx >= 0 ? rest.slice(sepIdx + 1) : [];
+        const scopeIdx = own.indexOf("--scope");
+        const scopeRaw = scopeIdx >= 0 ? own[scopeIdx + 1] : undefined;
+        // 결정 411: scope 오타를 조용히 전체 실행으로 폴백하지 않는다(--pm 오타를 막은
+        // 결정 167 과 대칭) — 통합만 돌리려던 CI 가 전체를 돌리며 실 인프라까지 띄운다.
+        if (scopeIdx >= 0 && scopeRaw !== "unit" && scopeRaw !== "integration" && scopeRaw !== "all") {
+            process.stderr.write(`  ✗ gaon test: --scope 값이 ${scopeRaw === undefined ? "없습니다" : `잘못됐습니다('${scopeRaw}')`}.\n` +
+                `    → 지원 값: unit · integration · all\n` +
+                `    → 예: gaon test --scope integration\n`);
+            process.exitCode = 2;
+            return;
+        }
+        const scope = scopeRaw !== undefined ? scopeRaw : undefined;
         const passthrough = [];
-        for (let i = 0; i < rest.length; i++) {
-            const a = rest[i];
+        for (let i = 0; i < own.length; i++) {
+            const a = own[i];
             if (a === "--scope") {
                 i++;
                 continue;
@@ -676,7 +758,8 @@ export function runCli(argv, opts = {}) {
             if (a !== undefined)
                 passthrough.push(a);
         }
-        void runTestCommand(passthrough, { json: argv.includes("--json"), scope })
+        passthrough.push(...forwarded);
+        void runTestCommand(passthrough, { json: own.includes("--json"), scope })
             .then((code) => {
             process.exitCode = code;
         })

package/dist/mcp/tools.js

@@ -603,6 +603,10 @@ export const TOOLS = [
                     description: '지정 시 그 검사 하나만 실행. 생략 시 전체.',
                 },
                 noDoctor: { type: 'boolean', description: 'true 면 doctor 를 제외(기본 false — doctor 는 기본 포함 · 결정 157).' },
+                // 결정 411: 폐기된 includeDoctor 를 스키마에 되살리지 **않는다**. 자리를 남기면
+                // strict 클라이언트의 구 호출이 "성공했는데 조용히 무시" 로 끝나 결정 362 가
+                // 없애려던 유령 파라미터 오도가 되살아난다 — 스키마 부재로 인한 검증 거부가
+                // 오히려 fail-loud(어느 파라미터를 쓰라는 신호)라 결정 362 계약을 유지한다.
             },
             additionalProperties: false,
         },

package/dist/messages-gen.js

@@ -4,7 +4,7 @@
 // 카탈로그의 키를 유니온 타입으로 물성화해, t('key') 의 존재하지 않는 키를 컴파일
 // 타임에 잡는다(현재는 GaonMessages 가 비어 있어 키가 string 으로 열림). 생성 파일은
 // 타입만 담는다(규칙 3). @gaonjs/i18n 의 공개 API(loadLocales·renderMessagesDts)만 쓴다.
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { loadLocales, renderMessagesDts } from '@gaonjs/i18n';
 /**
@@ -13,11 +13,19 @@ import { loadLocales, renderMessagesDts } from '@gaonjs/i18n';
  * 안 쓰는 프로젝트가 never 로 깨지지 않게). 생성 여부를 돌려준다.
  */
 export function generateMessagesDts(localesDir, out, baseLng) {
-    if (!existsSync(localesDir))
+    // 결정 414: 카탈로그가 사라졌으면 **옛 생성물을 지운다** — 남겨두면 없어진 키의
+    // 유니온이 그대로 살아 t('없어진키') 가 계속 컴파일된다(제거를 못 잡는 사각).
+    if (!existsSync(localesDir)) {
+        if (existsSync(out))
+            rmSync(out, { force: true });
         return false;
+    }
     const resources = loadLocales(localesDir);
-    if (Object.keys(resources).length === 0)
+    if (Object.keys(resources).length === 0) {
+        if (existsSync(out))
+            rmSync(out, { force: true });
         return false;
+    }
     mkdirSync(dirname(out), { recursive: true });
     // 결정 352: 기준 로케일 = config i18n.fallbackLng(호출자가 정적 분석으로 전달).
     // 이전엔 항상 알파벳순 첫 로케일이라 컴파일 보증이 fallback 체인과 다른 로케일에

package/dist/templates/project/Dockerfile.tpl

@@ -18,12 +18,22 @@ RUN pnpm install --frozen-lockfile
 FROM base AS build
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .
+# 결정 408: 브라우저에 실리는 공개 변수(VITE_*)는 **빌드 시점에 번들로 각인**된다 —
+# 런타임 env(compose.prod.yaml)로는 못 바꾼다. 값이 필요하면 빌드 인자로 넘긴다:
+#   docker build --build-arg VITE_API_BASE=https://api.example.com .
+# 넘기지 않으면 아래 .env.example 의 placeholder 가 그대로 각인되므로, 공개 변수를
+# 쓰는 앱은 반드시 build-arg 로 주거나 .env.example 에 **공개 가능한 실값**을 둔다.
+# (비밀은 VITE_ 로 만들지 말 것 — 번들은 누구나 읽는다.)
+ARG VITE_VARS=""
 # gaon build 는 .gaon/env.d.ts 생성에 .env 가 필수(결정 198)인데 .env 는 이미지에
 # 넣지 않는다(.dockerignore) — .env.example 을 임시 복제해 빌드하고 즉시 지운다.
 # 지우는 이유: example 의 placeholder(SESSION_SECRET 등)가 런타임에 남으면 compose
 # 가 env 를 안 넘겼을 때 fail-loud 검증을 조용히 통과시킨다(결정 313). 런타임 env
 # 는 compose.prod.yaml 의 environment 가 단일 소스다.
-RUN cp .env.example .env && pnpm build && rm -f .env
+RUN cp .env.example .env \
+  && for kv in $VITE_VARS; do printf '%s\n' "$kv" >> .env; done \
+  && pnpm build \
+  && rm -f .env
 
 # 3) 런타임 — 소스 + 번들 + 의존을 그대로 실행.
 FROM base AS runtime

package/dist/templates/project/agents/async.md.tpl

@@ -191,7 +191,10 @@ await OrderPlaced.emit({ orderId: 1n })
 - 실패하면 백오프(잡과 같은 곡선 `[1s, 5s, 30s, 5m, 1h]`)로 재전달되고, 최대
   재전달(기본 6 · 최초 포함) 소진 시 **영구 폐기**된다. 즉 계속 실패하는 이벤트는
   약 **1시간 36분** 뒤 사라진다 — `gaon work` 가 `✗ 이벤트 폐기` 로 신호한다
-  (결정 308 · 이전엔 human 모드 무신호). 놓치면 안 되는 처리는 리스너에서 잡을
+  (결정 308 · 이전엔 human 모드 무신호). **크래시 루프**(핸들러 throw 가 아니라
+  프로세스가 ack 전에 반복 사망)로 소진돼도 MAX_DELIVERIES advisory 백스톱이
+  같은 `✗ 이벤트 폐기` 신호를 낸다(결정 398 · 잡의 결정 347 동형 · advisory 는
+  비영속이라 best-effort). 놓치면 안 되는 처리는 리스너에서 잡을
   발행해(`.later()`) 잡의 재시도·DLQ 배터리로 넘긴다.
 - **리스너별 순차 처리는 보장되지 않는다** — 재시도 대기 중 다음 이벤트가 먼저
   처리될 수 있고, 드물게 같은 리스너의 두 이벤트가 겹칠 수 있다. 순서·중복에
@@ -235,15 +238,20 @@ export const PlaceOrder = service(async (input: { name: string }) => {
   어떤 경로로도 삭제되지 않으므로 유실이 없다.
 - at-least-once — 발행 후 표시하므로 중복 가능성이 있고, dedup(msgID)이
   흡수한다(claim 리스 60s < dedupe 창 120s 라 "발행 후 표시 전 크래시"
-  재발행도 창 안에서 접힌다).
+  재발행도 창 안에서 접힌다). **"claim 리스 < dedupe 창" 은 부팅이 강제한다
+  (결정 396)** — `dedupeWindowMs` 를 claim 아래로 줄이는 오설정은 조용한 이중
+  배달이 되므로 `gaon work` 가 수리 안내와 함께 fail-loud 한다. claim 리스는
+  env `GAON_OUTBOX_CLAIM_TIMEOUT_MS`(또는 `runWork` 의 `outboxClaimTimeoutMs`)
+  로 조정한다.
 - 아웃박스 테이블(`_gaon_outbox`)은 코어 내장이며 `gaon serve`·`gaon work`
   기동 시 보장된다(결정 144 · nats 설정이 있을 때).
 - 발행 완료 행은 릴레이가 **자동 정리(purge)** 한다 — 기본 7일 보존 후 삭제
-  (결정 78). 수동 cleanup 코드를 쓰지 말 것. 보존 기간·간격·폴링 주기는 env
-  `GAON_OUTBOX_RETENTION_MS`·`GAON_OUTBOX_PURGE_INTERVAL_MS`·`GAON_OUTBOX_RELAY_POLL_MS`
+  (결정 78). 수동 cleanup 코드를 쓰지 말 것. 보존 기간·간격·폴링 주기·claim 리스는 env
+  `GAON_OUTBOX_RETENTION_MS`·`GAON_OUTBOX_PURGE_INTERVAL_MS`·`GAON_OUTBOX_RELAY_POLL_MS`·
+  `GAON_OUTBOX_CLAIM_TIMEOUT_MS`(결정 396)
   로 조정한다(결정 312 · `GAON_WORKER_*` 와 대칭 · `gaon work` 가 읽는다). 프로그래매틱
-  경로는 `runWork()` 의 `outboxRetentionMs`·`outboxPurgeIntervalMs`·`relayPollMs`.
-  미발행 행은 절대 삭제되지 않는다.
+  경로는 `runWork()` 의 `outboxRetentionMs`·`outboxPurgeIntervalMs`·`relayPollMs`·
+  `outboxClaimTimeoutMs`. 미발행 행은 절대 삭제되지 않는다.
 - **발행 실패는 행 단위로 격리된다(결정 306 · 346).** 한 행의 publish 가 실패해도
   (예: 페이로드가 NATS `max_payload` 1MiB 초과) 그 행만 claim 된 채 남아 리스
   만료(60s) 후 재시도되고, 뒤 행들은 정상 발행된다 — 한 행이 아웃박스 전체를
@@ -301,7 +309,8 @@ export default schedule((s) => {
   워커에 로드밸런싱된다. 발행은 1인, 처리는 N인.
 - **exactly-once(발행 기준)** — 한 스케줄 틱은 리더 1인이 한 번만 발행한다.
   리더 교체(페일오버) 순간 구·신 리더가 같은 틱을 겹쳐 발행해도, 결정론적
-  dedupe 키 + JetStream 중복 윈도우가 이를 1회로 수렴시킨다(결정 233).
+  dedupe 키 + JetStream 중복 윈도우가 이를 1회로 수렴시킨다 — cron 은 발화
+  분(minute) 키(결정 233), **every 는 위상 슬롯 키**(결정 394 · 아래)로 접힌다.
   잡 자체는 재시도(백오프)가 있으니 **핸들러는 멱등**하게 짠다(같은 잡이 두 번
   처리돼도 안전하게).
 - **`s.every` 위상은 리더 교체를 가로질러 보존된다(결정 349).** 마지막 발화
@@ -309,6 +318,13 @@ export default schedule((s) => {
   아니면 잔여 시간만 기다린다 — 재선출마다 타이머가 리셋돼 리스 플래핑이
   interval 보다 잦으면 every 잡이 영영 안 돌던 기아가 없다. 리스 갱신도 순단
   1~2회는 재시도 후에만 리더를 내려놓는다(불필요한 failover·리셋 억제).
+- **`s.every` 의 failover 이중발화도 접힌다(결정 394).** 구 리더가 발화 직후
+  위상 기록(KV put · best-effort)을 못 남기고 죽으면 신 리더가 같은 슬롯을
+  즉시 재발화하는데, every 발화가 위상 슬롯 기반 결정적 dedupe 키
+  (`enqueueScheduled`)를 쓰므로 같은 슬롯의 재발화는 JetStream 중복 윈도우
+  안에서 1건으로 수렴한다 — 결정 349 이후 every 만 랜덤 id(`later()`)라
+  안 접히던 창을 닫았다. 사임(stop) 시 리스 키 삭제도 CAS 라 stale 리더의
+  종료가 신 리더의 키를 지우지 않는다(결정 395).
 - **`gaon serve` 는 스케줄러를 돌리지 않는다** — 스케줄·리더 선출·아웃박스
   릴레이는 **`gaon work` 전용**이다. 웹 프로세스는 잡을 **발행**만 할 수 있고
   (`.later()`), 처리·스케줄은 워커가 한다. **운영에서** 스케줄이 안 도는 흔한
@@ -352,6 +368,9 @@ drain — 스케줄러 리더를 반납하고 진행 중인 잡을 완료한 뒤
 - **`gaon work`** — 신규 잡 pull 을 멈추고 **진행 중 잡을 완료**한 뒤 종료한다
   (`drainTimeoutMs` 상한 · 기본 30s). 스케줄러 리더는 즉시 반납해 다른 인스턴스가
   승계한다. drain 상한을 넘긴 잡은 ack 되지 않아 재전달(크래시 복구)된다.
+  상한은 **큐가 동시성 포화 상태로 긴 잡을 물고 있어도** 지켜진다(결정 397 —
+  종전엔 이 경우 소비 루프 종료 대기가 상한 밖이라 stop 이 잡 완료까지 무기한
+  붙들렸다).
 - **컨테이너 기본 워커 1** — `gaon serve` 클러스터(`--workers`)도 SIGTERM 에
   워커들을 graceful drain 후 종료한다(결정 84).
 
@@ -463,6 +482,10 @@ async create() {
   발행은 `afterCommit()` 또는 아웃박스로.
 - **테스트에서 NATS 목업 금지** (§9) — 실 JetStream 에 접속한다
   (`agents/testing.md`).
+- **MySQL 은 8.0+(`explicit_defaults_for_timestamp=ON`) 전제** (결정 400) —
+  구식 설정(OFF · 5.7 기본)에서는 아웃박스 테이블의 timestamp 컬럼이 NOT NULL
+  + zero-date 기본으로 생성돼 strict `NO_ZERO_DATE` 와 충돌할 수 있다. 관리형
+  MySQL 에서 해당 플래그가 OFF 면 ON 으로 바꿔라.
 - **동시 실행 방지에 로컬 뮤텍스·플래그 금지** (결정 147) — `let running = false`
   같은 프로세스 로컬 가드는 멀티 인스턴스에서 안 먹는다. `lock(key, fn)` 을
   쓴다. 운영에서 `redis` 미설정이면 `lock()` 이 수리 안내로 throw 하니 조용한
@@ -493,4 +516,10 @@ async create() {
 | 결정 348 | 워커 큐별 동시성 게이트(§1) — 전역 inflight 비교가 낳던 교차 큐 간섭 제거(선언 `concurrency` = 실제 동시 처리) |
 | 결정 349 | 리스 갱신 순단 재시도 + every 위상 KV 보존(§5) — 키가 내 것이면 revision 동기화 재시도 후에만 revoke · `gaon_scheduler` KV 로 위상 이어받기(플래핑 기아 봉합) |
 | 결정 351 | DLQ 조회 배치 스캔(§1) — ordered 컨슈머 fetch 로 삭제 갭 서버 스킵 · findDlq 1000건 상한 제거(옛 레코드 retry 복원) |
+| 결정 394 | every failover 이중발화 dedupe(§5) — 위상 슬롯 기반 결정적 키(`enqueueScheduled`)로 구·신 리더의 같은 슬롯 재발화가 1건으로 수렴(결정 349 가 연 창 봉합 · cron 결정 233 동형) |
+| 결정 395 | 리스 사임 CAS 삭제(§5) — stop() 이 `previousSeq` 로 자기 revision 에서만 키 삭제 · stale 리더 종료가 신 리더 키를 지우던 재선출 순단 봉합(허브 endpoint 결정 259 동형) |
+| 결정 396 | 아웃박스 claim<dedupe 불변식 부팅 강제(§4) — 위반 시 fail-loud(조용한 이중 배달 봉합) · claim 리스 운영 표면 `GAON_OUTBOX_CLAIM_TIMEOUT_MS`/`outboxClaimTimeoutMs` 신설 |
+| 결정 397 | graceful drain 상한 유계화(§6) — 포화 큐의 긴 잡이 소비 루프 종료를 붙들어 `drainTimeoutMs` 가 무효이던 우회 봉합(closers 도 같은 deadline 공유 · 워커·리스너 공통) |
+| 결정 398 | 리스너 크래시 루프 소진 신호(§3) — EVENTS 스트림 MAX_DELIVERIES advisory 백스톱으로 `dropped` 신호(잡 결정 347 동형 · 공유 스트림이라 메시지 삭제는 안 함) |
+| 결정 400 | P3 청소 묶음 — 허브 KV 복원 오염 키 방어(try/continue) · 라인 디코더 완결 초과 라인도 onOverflow(무신호 명령 소실 금지) · MySQL timestamp 모드 함정 문서화 · listDlq 롤링 버퍼(O(limit) 메모리) · advisory dead 는 삭제 성공 워커만 신호 + 삭제 실패 잔류 관측 |
 | §7 | 비동기 배터리 원문 (백오프 기본값 = M7 벤치마크 확정) |