@gaonjs/cli 0.26.0 → 0.27.0

package/dist/doctor/link-button-nesting.d.ts

@@ -0,0 +1,5 @@
+import type { RuleReport } from './types.js';
+/** 소스에 Link>Button 이중 감싸기가 있는지(단위 테스트 진입점 · 주석 제외). */
+export declare function usesLinkButtonNesting(source: string): boolean;
+/** apps/ 의 .vue 를 훑어 Link>Button 이중 감싸기를 경고로 낸다. */
+export declare function checkLinkButtonNesting(cwd: string): Promise<RuleReport>;

package/dist/doctor/link-button-nesting.js

@@ -0,0 +1,92 @@
+// @gaonjs/cli · doctor · Link 로 Button 을 감싼 이중 표면 검출 (결정 113 · 경고)
+//
+// `<Link href="/x"><Button>…</Button></Link>` 는 <a><button> 중첩을 만든다 —
+// HTML 비준수(인터랙티브 요소 안에 인터랙티브 요소)이고 접근성 결함이다(첫·넷째
+// 실사용 블로그에서 관측). 버튼 모양 링크는 한 표면으로 낸다: `<Button href="/x">`.
+// Button 이 href 를 받으면 내부에서 gaonjs/vue 의 Link(=<a> · SPA 이동)로 렌더한다.
+//
+// 판정은 소스 텍스트 기반. 오탐 방지: Link 가 **직계 자식으로 Button 을** 감쌀
+// 때만 잡는다(Link 의 `>` 바로 뒤가 `<Button`). 텍스트·다른 요소를 감싼 Link 나
+// Button 을 안 쓰는 Link 는 건드리지 않는다.
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+// 주석을 공백으로 치환하되 줄바꿈은 보존한다(라인 번호 유지) — 안티패턴을
+// "쓰지 말라"고 설명하는 주석이 오탐을 내지 않도록.
+function stripCommentsKeepLines(source) {
+    const blank = (m) => m.replace(/[^\n]/g, ' ');
+    return source
+        .replace(/\/\*[\s\S]*?\*\//g, blank)
+        .replace(/<!--[\s\S]*?-->/g, blank)
+        .replace(/(^|[^:])\/\/[^\n]*/g, (_m, p1) => p1 + ' '.repeat(_m.length - p1.length));
+}
+// Link 여는 태그 하나에서 href(정적 또는 바인딩)를 뽑는다 — 수리 안내 문구용(없으면 null).
+function linkHref(openTag) {
+    const staticM = openTag.match(/\shref\s*=\s*(['"])([^'"]*)\1/i);
+    if (staticM)
+        return staticM[2].trim();
+    const boundM = openTag.match(/(?::|v-bind:)href\s*=\s*(['"])([^'"]*)\1/i);
+    if (boundM)
+        return boundM[1] === '"' ? `:href="${boundM[2].trim()}"` : `:href='${boundM[2].trim()}'`;
+    return null;
+}
+// Link 가 직계 자식으로 Button 을 감싸는 패턴(주석 제거 후 소스 대상).
+// `<Link ...>`(자기닫힘 아님) 바로 뒤(공백만 허용)가 `<Button`.
+const WRAP_RE = /<Link\b([^>]*)>\s*<Button\b/i;
+/** 소스에 Link>Button 이중 감싸기가 있는지(단위 테스트 진입점 · 주석 제외). */
+export function usesLinkButtonNesting(source) {
+    return WRAP_RE.test(stripCommentsKeepLines(source));
+}
+/** apps/ 의 .vue 를 훑어 Link>Button 이중 감싸기를 경고로 낸다. */
+export async function checkLinkButtonNesting(cwd) {
+    const appsDir = join(cwd, 'apps');
+    const issues = [];
+    for (const abs of await walkVue(appsDir)) {
+        const source = await readFile(abs, 'utf8').catch(() => '');
+        const stripped = stripCommentsKeepLines(source);
+        const rel = relative(cwd, abs);
+        for (const m of stripped.matchAll(/<Link\b([^>]*)>\s*<Button\b/gi)) {
+            const line = stripped.slice(0, m.index ?? 0).split('\n').length;
+            const href = linkHref(`<Link${m[1]}>`);
+            const hrefAttr = href === null ? 'href="/…"' : href.startsWith(':') ? href : `href="${href}"`;
+            issues.push({
+                rule: 'link-button-nesting',
+                level: 'warning',
+                file: rel,
+                line,
+                message: `Link 가 Button 을 감쌌습니다: ${rel}:${line} 의 \`<Link><Button>…</Button></Link>\` 는 ` +
+                    `<a><button> 중첩(HTML 비준수·접근성 결함)입니다.\n` +
+                    `→ 버튼 모양 링크는 한 표면 \`<Button ${hrefAttr}>…</Button>\` 로 내세요 — Button 이 ` +
+                    `href 를 받으면 내부에서 SPA 이동 링크로 렌더합니다(결정 113). 외부 URL 이면 ` +
+                    `\`<Button ${hrefAttr} external target="_blank">\`. Link 로 감싸지 마세요.`,
+                detail: { file: rel, line, href },
+            });
+        }
+    }
+    return { rule: 'link-button-nesting', issues };
+}
+/** apps/ 하위 .vue(선언·테스트 제외) 절대경로. */
+async function walkVue(dir) {
+    const out = [];
+    const walk = async (d) => {
+        let entries;
+        try {
+            entries = await readdir(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const abs = join(d, e.name);
+            if (e.isDirectory()) {
+                if (e.name === 'node_modules' || e.name === '.gaon')
+                    continue;
+                await walk(abs);
+            }
+            else if (e.isFile() && e.name.endsWith('.vue')) {
+                out.push(abs);
+            }
+        }
+    };
+    await walk(dir);
+    return out.sort();
+}

package/dist/doctor/types.d.ts

@@ -1,4 +1,4 @@
-export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-composable-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'column-casing' | 'model-filename' | 'page-filename' | 'auth-wiring' | 'ui-kit-wiring' | 'route-registration' | 'static-collision' | 'method-override' | 'csrf-wiring' | 'internal-anchor' | 'pageprops-destructure' | 'async-offload' | 'page-layout-breakpoint';
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-composable-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'column-casing' | 'model-filename' | 'page-filename' | 'auth-wiring' | 'ui-kit-wiring' | 'route-registration' | 'static-collision' | 'method-override' | 'csrf-wiring' | 'internal-anchor' | 'pageprops-destructure' | 'async-offload' | 'page-layout-breakpoint' | 'link-button-nesting';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor.d.ts

@@ -20,6 +20,7 @@ export { internalAnchorHref, usesInternalAnchor, checkInternalAnchor, } from './
 export { usesPagePropsDestructure, checkPagePropsDestructure, } from './doctor/pageprops-destructure.js';
 export { isApiApp, importsMailSdk, importsImageLib, callsExternalHttp, pageActions, checkAsyncOffload, } from './doctor/async-offload.js';
 export { usesLayoutBreakpoint, checkPageLayoutBreakpoint, } from './doctor/page-layout-breakpoint.js';
+export { usesLinkButtonNesting, checkLinkButtonNesting, } from './doctor/link-button-nesting.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 export interface DoctorCommandOptions {

package/dist/doctor.js

@@ -1,7 +1,7 @@
 /**
  * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성 · E-5 확장)
  *
- * 22 검사를 조립한다:
+ * 23 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
@@ -24,6 +24,7 @@
  * 20) pageprops-destructure (결정 99 · pageProps() 구조분해 = 반응성 끊김 경고)
  * 21) async-offload (결정 102·103 · 컨트롤러 인라인 메일·이미지·외부 HTTP = 응답 지연 경고)
  * 22) page-layout-breakpoint (결정 107 · 페이지 레이아웃 브레이크포인트 직접 사용 = 안내 경고)
+ * 23) link-button-nesting (결정 113 · Link 로 Button 감싸기 = <a><button> 중첩 경고)
  *
  * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
  * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
@@ -58,6 +59,7 @@ import { checkInternalAnchor } from './doctor/internal-anchor.js';
 import { checkPagePropsDestructure } from './doctor/pageprops-destructure.js';
 import { checkAsyncOffload } from './doctor/async-offload.js';
 import { checkPageLayoutBreakpoint } from './doctor/page-layout-breakpoint.js';
+import { checkLinkButtonNesting } from './doctor/link-button-nesting.js';
 import { renderHuman, renderJson } from './doctor/reporter.js';
 import { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 import { makeResult, } from './doctor/types.js';
@@ -81,10 +83,11 @@ export { internalAnchorHref, usesInternalAnchor, checkInternalAnchor, } from './
 export { usesPagePropsDestructure, checkPagePropsDestructure, } from './doctor/pageprops-destructure.js';
 export { isApiApp, importsMailSdk, importsImageLib, callsExternalHttp, pageActions, checkAsyncOffload, } from './doctor/async-offload.js';
 export { usesLayoutBreakpoint, checkPageLayoutBreakpoint, } from './doctor/page-layout-breakpoint.js';
+export { usesLinkButtonNesting, checkLinkButtonNesting, } from './doctor/link-button-nesting.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 21개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 23개 모두.
  */
 const ALL_RULES = [
     'response-mixing',
@@ -109,6 +112,7 @@ const ALL_RULES = [
     'pageprops-destructure',
     'async-offload',
     'page-layout-breakpoint',
+    'link-button-nesting',
 ];
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
@@ -133,6 +137,7 @@ const CHECKERS = {
     'pageprops-destructure': checkPagePropsDestructure,
     'async-offload': checkAsyncOffload,
     'page-layout-breakpoint': checkPageLayoutBreakpoint,
+    'link-button-nesting': checkLinkButtonNesting,
 };
 /**
  * 규칙을 순서대로 실행해 RuleReport[] 를 낸다. 규칙 하나가 크래시해도 나머지는

package/dist/index.js

@@ -101,7 +101,7 @@ function renderHelp(version = VERSION) {
         "    gaon check         typecheck · vue-tsc · build 통합 검사 (--only <step> · --include-doctor)",
         "    gaon console       프로젝트 컨텍스트 REPL (--no-config)",
         "    gaon test          테스트 러너 (테스트 DB <db>_test 자동 생성·마이그레이션 후 vitest · --scope unit|integration|all · -- vitest 인자)",
-        "    gaon doctor        정적 검사 (22 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트)",
+        "    gaon doctor        정적 검사 (23 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트·Link>Button 중첩)",
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon doctor --fix                         기계 정정 가능한 위반 계획(dry-run · v0.16 §7.5.3)",

package/dist/templates/auth/Dashboard.vue.tpl

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { pageProps, router } from 'gaonjs/vue'
+import { useShared, router } from 'gaonjs/vue'
 import Card from '@shared/components/ui/Card.vue'
 import CardHeader from '@shared/components/ui/CardHeader.vue'
 import CardTitle from '@shared/components/ui/CardTitle.vue'
@@ -8,25 +8,24 @@ import CardContent from '@shared/components/ui/CardContent.vue'
 import CardFooter from '@shared/components/ui/CardFooter.vue'
 import Button from '@shared/components/ui/Button.vue'
 
-// dashboard#show 의 render props — user 는 직렬화되며 passwordDigest 는 없다(§4.2).
-// pageProps 는 반응형 — 변수로 받아 props.x 로 접근한다(구조분해 금지 · 결정 99).
-const props = pageProps<'{{APP_NAME}}:dashboard#show'>()
+// 사용자·csrf 는 자동 주입 공유 prop 이다(결정 116) — 컨트롤러가 넘기지 않고
+// useShared() 로 읽는다. currentUser 는 직렬화됨(passwordDigest 없음 · §4.2).
+// 이 페이지는 requireAuth 로 보호되므로 런타임엔 항상 로그인 상태(타입은 nullable).
+const shared = useShared()
 
 // 로그아웃 = DELETE /session (r.resource('session') 의 destroy).
-// HTML <form> 은 DELETE 를 보낼 수 없으므로 Inertia 라우터로 실제 메서드를
-// 보낸다(결정 64) — `?_method=DELETE` 우회는 서버가 해석하지 않아 POST /session
-// (= 로그인 create) 으로 잘못 라우팅됐다.
+// HTML <form> 은 DELETE 를 못 보내므로 Inertia 라우터로 실제 메서드를 보낸다(결정 64).
 function logout(): void {
-  router.delete('/session', { headers: { 'x-csrf-token': props.csrf } })
+  router.delete('/session', { headers: { 'x-csrf-token': shared.csrf } })
 }
 </script>
 
 <template>
   <div class="mx-auto max-w-2xl px-4 py-10">
-    <Card>
+    <Card v-if="shared.currentUser">
       <CardHeader>
-        <CardTitle>환영합니다, {{ props.user.name }}님</CardTitle>
-        <CardDescription>{{ props.user.email }}</CardDescription>
+        <CardTitle>환영합니다, {{ shared.currentUser.name }}님</CardTitle>
+        <CardDescription>{{ shared.currentUser.email }}</CardDescription>
       </CardHeader>
       <CardContent>
         <p class="text-sm text-muted-foreground">보호된 페이지입니다 — this.requireAuth() 로 지킵니다.</p>

package/dist/templates/auth/Login.vue.tpl

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { pageProps, useForm, Link } from 'gaonjs/vue'
+import { pageProps, useForm, useShared, Link } from 'gaonjs/vue'
 import Card from '@shared/components/ui/Card.vue'
 import CardHeader from '@shared/components/ui/CardHeader.vue'
 import CardTitle from '@shared/components/ui/CardTitle.vue'
@@ -17,9 +17,12 @@ import AlertDescription from '@shared/components/ui/AlertDescription.vue'
 // 실패로 서버가 같은 페이지를 다시 render 하면 props.error 가 즉시 갱신된다.
 const props = pageProps<'{{APP_NAME}}:session#new'>()
 
+// csrf 는 자동 주입 공유 prop 이다(결정 116) — useShared() 로 읽는다.
+const shared = useShared()
+
 // 세션 앱 폼 = Inertia SPA 제출(결정 64) — fetch() 로 만들지 않는다.
 // 서버는 redirect(Inertia 응답)로 답하고, 실패 시 같은 페이지를 다시 render 한다.
-const form = useForm({ email: '', password: '', _csrf: props.csrf })
+const form = useForm({ email: '', password: '', _csrf: shared.csrf })
 </script>
 
 <template>

package/dist/templates/auth/Signup.vue.tpl

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { pageProps, useForm, Link } from 'gaonjs/vue'
+import { pageProps, useForm, useShared, Link } from 'gaonjs/vue'
 import Card from '@shared/components/ui/Card.vue'
 import CardHeader from '@shared/components/ui/CardHeader.vue'
 import CardTitle from '@shared/components/ui/CardTitle.vue'
@@ -15,8 +15,11 @@ import AlertDescription from '@shared/components/ui/AlertDescription.vue'
 // pageProps 는 반응형 — 변수로 받아 props.x 로 접근한다(구조분해 금지 · 결정 99).
 const props = pageProps<'{{APP_NAME}}:registration#new'>()
 
+// csrf 는 자동 주입 공유 prop 이다(결정 116) — useShared() 로 읽는다.
+const shared = useShared()
+
 // 세션 앱 폼 = Inertia SPA 제출(결정 64) — fetch() 로 만들지 않는다.
-const form = useForm({ name: '', email: '', password: '', _csrf: props.csrf })
+const form = useForm({ name: '', email: '', password: '', _csrf: shared.csrf })
 </script>
 
 <template>

package/dist/templates/auth/dashboard.controller.ts.tpl

@@ -4,8 +4,9 @@ import { controller } from 'gaonjs/web'
 export default controller({
   // GET /dashboard — 로그인해야 볼 수 있는 보호 페이지. 비로그인은 로그인으로 보내진다.
   async show() {
-    const user = this.requireAuth()
-    // csrf 는 로그아웃(DELETE /session · 결정 64)이 헤더로 실어 보낸다.
-    return this.render('Dashboard', { user, csrf: this.csrfToken() })
+    // 보호만 하고 페이지 데이터는 넘기지 않는다 — 사용자·csrf 는 자동 주입되고
+    // (결정 116), 페이지는 useShared() 로 읽는다. requireAuth 로 게이트만 건다.
+    this.requireAuth()
+    return this.render('Dashboard', {})
   },
 })

package/dist/templates/auth/registration.controller.ts.tpl

@@ -3,9 +3,9 @@ import { controller, hashPassword } from 'gaonjs/web'
 import { User } from '../../../domain/models/User.js'
 
 export default controller({
-  // GET /registration/new — 회원가입 폼
+  // GET /registration/new — 회원가입 폼. csrf 는 자동 주입된다(결정 116).
   async new() {
-    return this.render('Auth/Signup', { error: null as string | null, csrf: this.csrfToken() })
+    return this.render('Auth/Signup', { error: null as string | null })
   },
   // POST /registration — 회원가입
   async create() {

package/dist/templates/auth/session.controller.ts.tpl

@@ -3,9 +3,9 @@ import { controller, verifyPassword } from 'gaonjs/web'
 import { User } from '../../../domain/models/User.js'
 
 export default controller({
-  // GET /session/new — 로그인 폼
+  // GET /session/new — 로그인 폼. csrf 는 자동 주입되므로 넘기지 않는다(결정 116).
   async new() {
-    return this.render('Auth/Login', { error: null as string | null, csrf: this.csrfToken() })
+    return this.render('Auth/Login', { error: null as string | null })
   },
   // POST /session — 로그인
   async create() {
@@ -18,7 +18,6 @@ export default controller({
     }
     return this.render('Auth/Login', {
       error: '이메일 또는 비밀번호가 올바르지 않습니다.' as string | null,
-      csrf: this.csrfToken(),
     })
   },
   // DELETE /session — 로그아웃

package/dist/templates/project/AGENTS.md.tpl

@@ -104,7 +104,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
   컬럼명 · 스키마 파일 ↔ 테이블 ↔ `tables.d.ts` 키 변환 규칙)은
   `agents/data.md` "DB 네이밍" 표가 정본이다 — 먼저 읽는다.
 
-### 2.2 `gaon doctor` 검사 22종
+### 2.2 `gaon doctor` 검사 23종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
@@ -128,6 +128,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 20. `pageprops-destructure` — `const { x } = pageProps(…)` 구조분해(반응성 끊김 · 리다이렉트/리로드 후 갱신 안 됨 · `const props = pageProps(…)` 후 `props.x` 로 접근하라) (결정 99 · 경고)
 21. `async-offload` — 컨트롤러 액션 인라인의 무거운/외부 작업(메일 SDK·이미지 처리 sharp/jimp·외부 HTTP)이 응답을 지연 (`domain/jobs/` 잡 + `.later()` 로 빼라 · JSON/API 앱 외부 호출·빠른 내부 호출은 오탐 방지로 제외) (결정 102·103 · 경고)
 22. `page-layout-breakpoint` — 페이지 파일이 레이아웃 브레이크포인트(`sm:flex-row`·`md:grid-cols-2` 등)를 직접 사용(반응형은 UI 킷 블록이 책임 · `PageShell` 등으로 감싸라 · 킷에 없는 표현이면 그대로 둬도 됨 · 표시/타이포/여백 반응형은 오탐 방지로 제외) (결정 107 · 안내 경고)
+23. `link-button-nesting` — `<Link><Button>…</Button></Link>` 이중 감싸기(`<a><button>` 중첩 · HTML 비준수·접근성 결함 · 버튼 모양 링크는 `<Button href="…">` 한 표면을 쓰라 · Link 직계 자식 Button 만 검출) (결정 113 · 경고)
 
 ## 3. 로직 배치 One Way 판단표
 
@@ -188,7 +189,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 ```bash
 gaon check        # .gaon 재생성 → typecheck + vue-tsc + build (+doctor)
 gaon test         # vitest — DB·NATS 는 실 인프라 (agents/testing.md)
-gaon doctor       # 정적 검사 22종 (§2.2)
+gaon doctor       # 정적 검사 23종 (§2.2)
 ```
 
 ### 4.1 CLI 명령 (전 명령 `--json` 지원)

package/dist/templates/project/CLAUDE.md.tpl

@@ -85,7 +85,7 @@ Gaon 프레임웍 문서: https://gaonjs.dev
 
 ```bash
 gaon check                        # .gaon 재생성 후 타입 검사 (CI 정합)
-gaon doctor                       # 정적 검사 17종 (응답·N+1·의존·커넥션·마이그·순수·자동import·파일명/컬럼·인증·UI킷·라우트 · 상세 AGENTS §2.2)
+gaon doctor                       # 정적 검사 23종 (상세 AGENTS §2.2)
 npm test                          # Vitest · DB 테스트는 실 Docker 필수 (§9)
 ```
 

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

@@ -195,6 +195,8 @@ export const posts = table('posts', {
 | `include` | `(...rels)` | `IncludedChain` | 관계 eager 로드 — **4종 전부**(belongsTo·hasMany·hasOne·belongsToMany, §1.1). **N+1 방지**: 관계당 쿼리 1회 (belongsToMany 는 피벗 `inner join` 1회) · 행 수와 무관. doctor 의 **n-plus-one** 검사가 include 미사용 · loop 안 관계 호출을 감지한다 |
 | `updateAll` | `(patch)` | `Promise<number>` | **벌크 갱신** (M2C) — where 조건만 반영 · 영향 행 수(number · 결정 90). limit·offset·orderBy 가 걸려 있으면 **throw** (Postgres `UPDATE ... LIMIT` 미지원 — 행을 좁히려면 `pluck('id')` → `whereIn('id', ids)`) |
 | `deleteAll` | `()` | `Promise<number>` | **벌크 삭제** (M2C) — 규칙은 updateAll 과 동일. 빈 where = 전체 삭제 (이름이 위험을 드러냄) |
+| `incrementAll` | `(field, by?=1)` | `Promise<number>` | **원자 벌크 증가**(결정 115) — `SET col = col + by` 한 문장 · 수치 컬럼 · 영향 행 수(number). 벌크 계약(limit/offset/orderBy 있으면 throw)은 updateAll 과 동일 |
+| `decrementAll` | `(field, by?=1)` | `Promise<number>` | **원자 벌크 감소**(결정 115) — `SET col = col - by`. incrementAll 의 대칭 |
 
 **집계·조인 그룹** (`Chain` · M2E · 결정 34):
 
@@ -261,6 +263,26 @@ export const posts = table('posts', {
   (§6 `Serialized<T>` 는 함수 값을 떨군다).
 - 사용자 메서드 (§8 `methods`) — `this` = Rec 으로 바인딩.
 
+**원자 프리미티브 (결정 115) — 카운터·플래그는 read-modify-write 하지 않는다:**
+
+값을 읽어 계산해 다시 쓰면(`rec.update({ views: rec.views + 1 })`) 동시 요청에서
+증가가 유실된다(경쟁 조건). SQL 표현식을 한 문장으로 실행하는 원자 메서드를 쓴다:
+
+- `rec.increment(field, by?=1)` / `rec.decrement(field, by?=1)` — `SET col = col ± by`.
+  **수치 컬럼만**(number·bigint). 갱신 후 값을 반환하고 `rec` 필드도 그 값으로 맞춘다.
+- `rec.touch(field?='updatedAt')` — 값을 읽지 않고 현재 시각으로 원자 갱신. **날짜 컬럼만** · `void`.
+- `rec.toggle(field)` — `SET col = NOT col`. **boolean 컬럼만** · 갱신 후 boolean 반환.
+- 컬렉션 버전은 체인 `incrementAll`·`decrementAll`(§4 표 · 영향 행 수 반환).
+
+```ts
+// domain/models/Post.ts — 조회수 카운터(원자 · 경쟁 조건 없음)
+methods: {
+  async recordView() {
+    return await this.increment('viewCount')   // NOT: this.update({ viewCount: this.viewCount + 1 })
+  },
+}
+```
+
 **체인 상태 전이 주의** (`model.ts:112-146`):
 
 - `select()`·`include()` 이후에도 빌더 메서드(`where`·`orWhere`·
@@ -395,6 +417,24 @@ export const Post = model(posts, {
 })
 ```
 
+- **여러 모델을 조합하는 읽기 질의도 이름을 붙인다 (§5.3 읽기 규칙 · 결정 114).**
+  검색·태그 필터처럼 여러 모델/서브쿼리를 엮는 읽기는 컨트롤러에 인라인 조립하지
+  않는다 — 주 모델이 분명하면 **모델 정적 메서드(스코프)**, 대등한 조합이면
+  `domain/services/` 로 이름을 붙인다. 컨트롤러에 허용되는 쿼리는 **스코프 체인
+  한 줄**까지다(`await Post.published().latest().limit(20).all()`).
+  ```ts
+  // ❌ 컨트롤러 인라인 조립 (검색 교집합을 컨트롤러가 조립)
+  //   const ids = await Post.where('title','ilike',p).orWhere('body','ilike',p).pluck('id')
+  //   const rows = await Post.published().whereIn('id', ids).latest().all()
+  // ✅ 이름 붙인 스코프 — 컨트롤러는 한 줄
+  scopes: {
+    searchPublished: (q, term: string) =>
+      q.where('published', '=', true)
+       .where('title', 'ilike', `%${term}%`).orWhere('body', 'ilike', `%${term}%`),
+  }
+  // 컨트롤러: const rows = await Post.searchPublished(term).latest().all()
+  ```
+
 ### 8.1 스키마 파생 폼 — `Model.form` · `Model.form.pick()` (결정 104)
 
 모든 모델은 `Model.form` 으로 **스키마 파생 폼**을 노출한다 — 컨트롤러의
@@ -652,4 +692,6 @@ await Post.upsert({ id, title, body })                // onConflict 생략 = 기
 | 결정 104 | 스키마 파생 폼에 name·defs 탑재(실검증) · `Model.form.pick()` 검증되는 부분 폼(§8.1) |
 | 결정 108 | 정적 default 컬럼 빈 입력 채움(§8.1) · 동적 default 는 DB 위임 |
 | 결정 110 | `latest()`·`orderBy` 정렬 뒤 PK 타이브레이커 자동 부가(결정적 페이지네이션 · §4) |
+| 결정 114 | 여러 모델 조합 읽기 = 이름 붙임(모델 정적 메서드/`domain/services/`) · 컨트롤러는 스코프 체인 한 줄까지(§8 · §5.3) |
+| 결정 115 | 원자 프리미티브 increment·decrement·touch·toggle(Rec) + incrementAll·decrementAll(Chain) · read-modify-write 금지(§4) |
 | E-4 | 컬럼 타입·수식어·체이닝 확장 · `Post.query()` 정정 · Serialized 명명 |

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

@@ -41,6 +41,16 @@ const props = pageProps<'web:posts#index'>()
 - **라우트 키** = `<app>:<controller>#<action>` (앱 폴더명 · 컨트롤러 파일명
   stem · 소문자 복수 · 결정 55). `apps/web/controllers/posts.ts` 의 `index`
   액션 → `'web:posts#index'`.
+- **공유 prop(currentUser·csrf·flash) = `useShared()`(결정 116) — 라우트 키 없이 읽는다.**
+  이 셋은 디스패처가 **모든** 렌더에 자동 주입하므로 컨트롤러가 넘기지 않는다(넘기면
+  컴파일 에러 · 결정 117). 레이아웃·컴포넌트에서 라우트를 모른 채 읽을 때 특히 유용하다:
+  ```vue
+  import { useShared } from 'gaonjs/vue'
+  const shared = useShared()            // { currentUser, csrf, flash } · 반응형
+  // <template> 에서 shared.currentUser?.name · shared.csrf · shared.flash.success
+  ```
+  `pageProps<K>()` 반환에도 교차되어 `props.csrf` 로도 읽히지만, 라우트 키가 필요 없는
+  `useShared()` 가 정본 표면이다(임의 라우트 키를 빌려 currentUser 를 읽던 우회 트릭을 없앤다).
 - **파사드는 `gaonjs/vue`** — `@gaonjs/vue` (스코프)·`@inertiajs/vue3` (내부 의존)
   로 import 하지 않는다.
 - **Gaon 은 `vue-router` 를 쓰지 않는다** — 라우팅은 **Inertia = SPA + 서버
@@ -258,6 +268,12 @@ import PageShell from '@shared/components/ui/PageShell.vue'
 - **`class` 는 폴스루로 병합** — 단일 루트 컴포넌트는 `<Button class="w-full">` 처럼
   넘긴 클래스가 루트로 흘러간다(별도 `class` prop 선언 없음). `cn` 은 충돌 클래스
   자동 해소를 하지 않는다 — 오버라이드가 잦으면 tailwind-merge 를 설치해 `cn` 만 교체.
+- **버튼 모양 링크 = `<Button href>`(결정 113) — `Link` 로 `Button` 을 감싸지 않는다.**
+  `<Link href="/x"><Button>…</Button></Link>` 는 `<a><button>` 중첩(HTML 비준수·접근성
+  결함)이다. `Button` 에 `href` 를 주면 내부에서 SPA 이동 링크(`Link`=`<a>`)로 렌더한다:
+  `<Button href="/posts/new">새 글</Button>`. 외부 URL 은 `<Button href="https://…" external
+  target="_blank">`. 순수 버튼은 `href` 없이 `<Button @click="…">`. doctor **link-button-nesting**
+  이 Link>Button 중첩을 경고한다.
 - **디자인 토큰은 `style.css` 한 곳(결정 74)** — 컴포넌트는 `bg-primary`·
   `text-muted-foreground` 같은 의미 토큰만 쓰고, 실색은 `apps/<앱>/style.css` 의
   `:root`/`.dark` CSS 변수에서 바꾼다(다크 모드 = `<html class="dark">`).
@@ -367,4 +383,6 @@ async function runSearch(q: string) {
 | 결정 106 | 최소 4블록(PageShell·PageHeader·EmptyState·Pagination · 성격 중립) |
 | 결정 107 | 반응형은 킷 책임(페이지 레이아웃 브레이크포인트 지양 · doctor page-layout-breakpoint 안내 경고 · 터치 44px·폰트 최소 크기 토큰) |
 | 결정 109 | 서버 스키마 검증 실패 → `form.errors.<field>` 자동 반영(303 back + 플래시 · `agents/web.md` §4.1) |
+| 결정 113 | 버튼 모양 링크 = `<Button href>`(Link 로 Button 감싸지 않음 · `<a><button>` 중첩 방지 · doctor link-button-nesting) |
+| 결정 116 | 공유 prop(currentUser·csrf·flash) 자동 주입 · `useShared()` 로 읽기(라우트 키 불요 · `agents/web.md`) |
 | E-3 §C | 타입드 `api()` 클라이언트 (routes.d.ts 브리지 재사용) |

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

@@ -167,12 +167,14 @@ redirect 로 처리한다 — 전체 페이지 리로드도, 별도 REST 엔드
 ```ts
 // 로그인 폼 — 제출은 Inertia SPA 방식, 서버는 redirect 로 답한다.
 // pageProps 는 반응형 — 변수로 받아 props.x 로 접근한다(구조분해 금지 · 결정 99).
+// csrf 는 자동 주입 공유 prop — useShared() 로 읽는다(결정 116).
 const props = pageProps<'web:session#new'>()
-const form = useForm({ email: '', password: '', _csrf: props.csrf })
+const shared = useShared()
+const form = useForm({ email: '', password: '', _csrf: shared.csrf })
 // <form @submit.prevent="form.post('/session')">  ·  실패 시 {{ props.error }} 가 반응형으로 갱신
 
 // HTML <form> 이 못 보내는 메서드(DELETE 등)는 router 로 보낸다.
-router.delete('/session', { headers: { 'x-csrf-token': props.csrf } })
+router.delete('/session', { headers: { 'x-csrf-token': shared.csrf } })
 ```
 
 `?_method=DELETE` 같은 우회는 **서버가 해석하지 않는다** — POST 로 나가
@@ -203,6 +205,44 @@ async create() {
 
 순수 JSON/API 앱(X-Inertia 아님·세션 없음)은 기존대로 **422 JSON** 을 받는다.
 
+### 4.2 공유 prop 자동 주입 — currentUser·csrf·flash (결정 116·117)
+
+디스패처가 **모든** Inertia 렌더에 공유 prop 3종을 자동 주입한다 — 컨트롤러가
+손으로 넘기지 않는다:
+
+- `currentUser` — 현재 로그인 사용자(직렬화 · 미로그인 `null`). 인증 augment 가 채운다.
+- `csrf` — 요청별 CSRF 토큰.
+- `flash` — 세션 플래시 백. `this.flash(key, value)` 로 심고(redirect-then-render),
+  다음 렌더의 `flash.<key>` 로 한 번 읽히면 소멸한다.
+
+페이지·레이아웃은 **`useShared()`(gaonjs/vue)** 로 라우트 키 없이 읽는다(결정 116 ·
+`agents/frontend.md` §1). `pageProps<K>()` 반환에도 교차되어 `props.csrf` 로도 읽힌다.
+
+- **예약 키는 render props 에 넣으면 컴파일 에러(결정 117).** `currentUser`·`csrf`·`flash`
+  는 자동 주입되므로 `this.render('p', { currentUser })` 는 타입 에러(+런타임 방어)다 —
+  그 이름을 페이지 데이터로 쓰지 말고, 필요하면 다른 이름을 쓴다.
+  ```ts
+  // ❌ 자동 주입값을 손으로 넘기지 않는다(컴파일 에러)
+  //   return this.render('Dashboard', { user, csrf: this.csrfToken() })
+  // ✅ 보호만 하고 페이지 데이터는 넘기지 않는다 — 페이지가 useShared() 로 읽는다
+  async show() {
+    this.requireAuth()
+    return this.render('Dashboard', {})
+  }
+  ```
+
+### 4.3 읽기 조합은 컨트롤러 인라인 조립하지 않는다 (§5.3 · 결정 114)
+
+컨트롤러 액션에 허용되는 쿼리는 **스코프 체인 한 줄**까지다. 검색·태그 필터처럼
+여러 모델/서브쿼리를 엮는 읽기는 이름을 붙인다 — 주 모델이 분명하면 **모델 정적
+메서드(스코프)**, 대등한 조합이면 `domain/services/`(`agents/data.md` §8). 컨트롤러가
+`pluck`·교집합·사이드바 질의를 인라인 조립하기 시작하면 서비스/스코프로 옮긴다.
+
+```ts
+// ❌ 컨트롤러가 검색 교집합·태그 필터를 인라인 조립
+// ✅ const rows = await Post.searchPublished(term).latest().offset(o).limit(n).all()
+```
+
 ### 5. 비밀번호 해싱 — `hashPassword` · `verifyPassword` (`gaonjs/web`)
 
 회원가입·로그인에서 비밀번호를 다룰 때는 **직접 crypto/bcrypt 를 import 하거나
@@ -372,4 +412,7 @@ export default controller({
 | 결정 104 | `Model.form.pick('a','b')` = 검증되는 부분 폼(결정 95 회부 종결) · 폼 변형은 pick 하나(omit/extend/merge 없음) |
 | 결정 108 | 정적 default 컬럼 빈 입력 채움(coerceParams) · 동적 default 는 DB 위임 |
 | 결정 109 | Inertia 폼 검증 실패 = 303 back + 플래시 errors → `useForm.errors` 자동(§4.1) · JSON/API 는 422 유지 |
+| 결정 114 | 여러 모델 조합 읽기는 이름 붙임(정적 메서드/서비스) · 컨트롤러는 스코프 체인 한 줄까지(§4.3 · `agents/data.md` §8) |
+| 결정 116 | 공유 prop(currentUser·csrf·flash) 자동 주입 · `this.flash(k,v)` · 페이지는 `useShared()`(§4.2) |
+| 결정 117 | render props 에 예약 공유 키 = 컴파일 에러 + 런타임 방어(자동 주입값 조용한 덮어쓰기 금지 · §4.2) |
 | E-1 | 파사드 = `gaonjs` · CLI = `gaon` |

package/dist/templates/ui-kit/Button.vue.tpl

@@ -1,14 +1,32 @@
 <script setup lang="ts">
-// UI 킷 · Button (결정 75). variant/size 로 모양을 고르고, 나머지 속성·클래스는
-// 자연스럽게 <button> 으로 흘러간다(Vue 폴스루). 부모가 class 를 주면 뒤에 병합된다.
+// UI 킷 · Button (결정 75 · 결정 113). variant/size 로 모양을 고르고, 나머지 속성·
+// 클래스는 자연스럽게 렌더 요소로 흘러간다(Vue 폴스루). 부모가 class 를 주면 뒤에 병합.
+//
+// 결정 113: 버튼 모양 링크는 `<Button href="/x">` 한 표면으로 낸다. `<Link>` 로
+// `<Button>` 을 감싸면 <a><button> 중첩(HTML 비준수·접근성 결함)이 된다 — 대신
+// href 를 주면 이 컴포넌트가 내부에서 알맞은 요소를 고른다:
+//   · href 있음(내부) → gaonjs/vue 의 <Link>(=<a> · SPA 이동)
+//   · href 있음 + external → 일반 <a>(target 지정 가능 · 외부 URL)
+//   · href 없음 → <button>
 import { computed } from 'vue'
+import { Link } from 'gaonjs/vue'
 import { cn } from '../../lib/utils.js'
 
 type Variant = 'default' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link'
 type Size = 'default' | 'sm' | 'lg' | 'icon'
 
 const props = withDefaults(
-  defineProps<{ variant?: Variant; size?: Size; type?: 'button' | 'submit' | 'reset' }>(),
+  defineProps<{
+    variant?: Variant
+    size?: Size
+    type?: 'button' | 'submit' | 'reset'
+    /** 주면 버튼 모양 링크가 된다(내부 이동은 SPA · 결정 113). Link 로 감싸지 말 것. */
+    href?: string
+    /** 외부 URL 이면 true — 일반 <a> 로 렌더(SPA 이동 아님). target 과 함께 쓴다. */
+    external?: boolean
+    /** external 링크의 target(예: '_blank'). */
+    target?: string
+  }>(),
   { variant: 'default', size: 'default', type: 'button' },
 )
 
@@ -28,12 +46,14 @@ const SIZES: Record<Size, string> = {
 }
 const BASE =
   'inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium ' +
-  'ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 ' +
+  'no-underline ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 ' +
   'focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50'
 
 const classes = computed(() => cn(BASE, VARIANTS[props.variant], SIZES[props.size]))
 </script>
 
 <template>
-  <button :type="type" :class="classes"><slot /></button>
+  <a v-if="href && external" :href="href" :target="target" :class="classes"><slot /></a>
+  <Link v-else-if="href" :href="href" :class="classes"><slot /></Link>
+  <button v-else :type="type" :class="classes"><slot /></button>
 </template>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Gaon CLI 구현: 제너레이터·스캐폴딩·로드맵 출력 (M1 스텁)",
   "type": "module",
   "license": "MIT",
@@ -27,12 +27,12 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
-    "@gaonjs/async": "0.6.1",
-    "@gaonjs/config": "0.6.0",
+    "@gaonjs/config": "0.7.0",
     "@gaonjs/core": "0.2.1",
-    "@gaonjs/web": "0.8.0",
-    "@gaonjs/data": "0.11.0",
-    "@gaonjs/mail": "0.1.3"
+    "@gaonjs/mail": "0.1.3",
+    "@gaonjs/web": "0.9.0",
+    "@gaonjs/data": "0.12.0",
+    "@gaonjs/async": "0.6.1"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""

package/dist/templates/auth/app.ts.tpl

@@ -1,29 +0,0 @@
-// 웹 앱 팩토리 — gaon g auth 스캐폴드. createWebApp 으로 세션·인증을 배선한다.
-import { createApp, type AppSessionOptions } from 'gaonjs/web'
-import appRoutes from './routes.js'
-import session from './controllers/session.js'
-import registration from './controllers/registration.js'
-import dashboard from './controllers/dashboard.js'
-import { loadUser } from './auth.js'
-
-export interface WebAppDeps {
-  /** 세션 설정 — { redisUrl, secret } (또는 redis 인스턴스). */
-  readonly session: AppSessionOptions
-  /** 서명 쿠키/CSRF 용 비밀. */
-  readonly cookieSecret?: string
-}
-
-export function createWebApp(deps: WebAppDeps) {
-  return createApp({
-    apps: [
-      {
-        name: '{{APP_NAME}}',
-        routes: appRoutes,
-        controllers: { session, registration, dashboard },
-        session: deps.session,
-        auth: { loadUser, loginRedirect: '/session/new' },
-      },
-    ],
-    cookieSecret: deps.cookieSecret,
-  })
-}

package/dist/templates/auth/server.ts.tpl

@@ -1,14 +0,0 @@
-// 서버 진입점 — gaon g auth 스캐폴드. `node dist/server.js` 로 실행.
-import { createWebApp } from './apps/{{APP_NAME}}/app.js'
-
-const app = await createWebApp({
-  session: {
-    redisUrl: process.env.REDIS_URL ?? 'redis://127.0.0.1:6379',
-    secret: process.env.SESSION_SECRET ?? 'change-me-to-a-32+char-random-secret!!',
-  },
-  cookieSecret: process.env.COOKIE_SECRET,
-})
-
-const port = Number(process.env.PORT ?? 3000)
-await app.listen({ port, host: '0.0.0.0' })
-console.log(`web 앱이 http://localhost:${port} 에서 실행 중입니다.`)