@gaonjs/cli 0.41.7 → 0.42.0

package/dist/commands/check.js

@@ -30,7 +30,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { generateTablesDts } from '@gaonjs/data';
 import { generateRoutesDts } from '@gaonjs/web';
-import { runDoctorCommand } from '../doctor.js';
+import { computeDoctorResult } from '../doctor.js';
 import { regenerateGaonOnce, resolveDevLayout } from '../dev.js';
 import { registerTsResolve } from '../tsResolve.js';
 import { listFrontendApps, verifyAppDist } from '../dev/build.js';
@@ -209,9 +209,11 @@ async function verifyBuildOutput(cwd) {
 /** doctor 는 이미 있는 명령을 재사용 — cwd 만 넘긴다. json 은 상위에서. */
 async function runDoctorStep(cwd) {
     try {
-        // runDoctorCommand 는 stdout 에 리포트를 그대로 찍는다. 결과 객체로
-        // 성공/실패를 판단한다.
-        const result = await runDoctorCommand({ cwd, json: false });
+        // computeDoctorResult 는 stdout 에 아무것도 쓰지 않고 결과만 돌려준다.
+        // runDoctorCommand 는 사람용 리포트를 stdout 에 직접 찍어 `gaon check --json`
+        // 의 순수 JSON 출력을 오염시켰다(mcp 의 parseJsonTail 우회가 방증). check 는
+        // 결과 객체만 필요하므로 무출력 경로를 쓴다(결정 269 · "--json = 파싱 안전").
+        const result = await computeDoctorResult({ cwd });
         const failed = !!result.fatal || result.errors.length > 0;
         return {
             step: 'doctor',

package/dist/commands/test.d.ts

@@ -3,6 +3,14 @@ export interface TestCommandOptions {
     readonly cwd?: string;
     readonly json?: boolean;
     readonly scope?: TestScope;
+    /**
+     * 프로그램 호출(MCP run_tests)용 출력 싱크. 지정되면 자식(vitest·test 스크립트)
+     * stdout/stderr 를 상속(inherit) 대신 파이프로 이 콜백에 흘린다 — 결과를 도구
+     * 응답에 담기 위함. CLI 경로(미지정)는 종전대로 `stdio:'inherit'`. 이 옵션으로
+     * MCP 가 `gaon test` 하네스(테스트 DB 프로비저닝·GAON_STREAM_PREFIX 격리·사용자
+     * test 스크립트 우선)를 그대로 거치게 한다(결정 270 · vitest 직접 spawn 우회 제거).
+     */
+    readonly onOutput?: (chunk: string) => void;
 }
 /**
  * `gaon test` 진입점. args 는 사용자가 넘긴 잔여 인자(필터 문자열 등).

package/dist/commands/test.js

@@ -67,7 +67,21 @@ function scopeArgs(scope) {
  * scope='unit' 은 실 인프라가 필요 없으므로 건너뛴다. config 가 없거나 db 커넥션이
  * 없으면 조용히 스킵(순수 vitest 위임). DB 접속 실패는 수리 안내와 함께 실패한다.
  */
-async function provisionTestDatabases(cwd, json) {
+async function provisionTestDatabases(cwd, json, onOutput) {
+    // capture(MCP) 모드는 stdio JSON-RPC 를 오염시키지 않도록 모든 출력을 싱크로
+    // 돌린다 — process.stdout 직접 쓰기 0(결정 270).
+    const writeOut = (s) => {
+        if (onOutput)
+            onOutput(s);
+        else
+            process.stdout.write(s);
+    };
+    const writeErr = (s) => {
+        if (onOutput)
+            onOutput(s);
+        else
+            process.stderr.write(s);
+    };
     registerTsResolve();
     let config;
     try {
@@ -93,7 +107,7 @@ async function provisionTestDatabases(cwd, json) {
             });
             if (res.exitCode !== 0) {
                 if (!json)
-                    process.stderr.write(`  ✗ 테스트 DB '${key}' 마이그레이션 실패\n${res.text}\n`);
+                    writeErr(`  ✗ 테스트 DB '${key}' 마이그레이션 실패\n${res.text}\n`);
                 return false;
             }
             prepared.push(key);
@@ -104,18 +118,18 @@ async function provisionTestDatabases(cwd, json) {
         const hint = `  ✗ 테스트 DB 준비 실패: ${msg}\n` +
             `  → DB 가 떠 있는지 확인하세요(docker compose up -d db). 테스트는 실 인프라가 필요합니다(§9).\n`;
         if (json)
-            process.stdout.write(JSON.stringify({ ok: false, kind: 'provision', error: msg }) + '\n');
+            writeOut(JSON.stringify({ ok: false, kind: 'provision', error: msg }) + '\n');
         else
-            process.stderr.write(hint);
+            writeErr(hint);
         return false;
     }
     finally {
         await destroyAllConnections();
     }
     if (json)
-        process.stdout.write(JSON.stringify({ kind: 'provisioned', dbs: prepared }) + '\n');
+        writeOut(JSON.stringify({ kind: 'provisioned', dbs: prepared }) + '\n');
     else
-        process.stdout.write(`  gaon test · 테스트 DB 준비 완료 (${prepared.join(', ')}) — <db>_test\n`);
+        writeOut(`  gaon test · 테스트 DB 준비 완료 (${prepared.join(', ')}) — <db>_test\n`);
     return true;
 }
 /**
@@ -127,9 +141,23 @@ export async function runTestCommand(args = [], opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const scope = opts.scope ?? 'all';
     const json = opts.json ?? false;
+    const capture = typeof opts.onOutput === 'function';
+    // capture(MCP) 모드: 모든 출력을 싱크로. 미지정: 종전대로 process.std*.
+    const writeOut = (s) => {
+        if (opts.onOutput)
+            opts.onOutput(s);
+        else
+            process.stdout.write(s);
+    };
+    const writeErr = (s) => {
+        if (opts.onOutput)
+            opts.onOutput(s);
+        else
+            process.stderr.write(s);
+    };
     // 결정 111: unit 이 아니면 실행 전 테스트 DB 를 준비한다(생성 + 마이그레이션).
     if (scope !== 'unit') {
-        const ok = await provisionTestDatabases(cwd, json);
+        const ok = await provisionTestDatabases(cwd, json, opts.onOutput);
         if (!ok)
             return 1;
     }
@@ -151,10 +179,10 @@ export async function runTestCommand(args = [], opts = {}) {
             const msg = `vitest 가 설치돼 있지 않고 package.json 에 "test" 스크립트도 없습니다.\n` +
                 `→ pnpm add -D vitest 후 다시 실행하거나, package.json 에 "test": "vitest run" 을 추가하세요.`;
             if (json) {
-                process.stdout.write(JSON.stringify({ ok: false, error: msg }) + '\n');
+                writeOut(JSON.stringify({ ok: false, error: msg }) + '\n');
             }
             else {
-                process.stderr.write(`  ✗ ${msg}\n`);
+                writeErr(`  ✗ ${msg}\n`);
             }
             return 127;
         }
@@ -168,20 +196,25 @@ export async function runTestCommand(args = [], opts = {}) {
     // 값을 세팅했으면 존중한다(고급 · 다중 테스트 컨텍스트 분리).
     const testEnv = { ...process.env, GAON_STREAM_PREFIX: process.env.GAON_STREAM_PREFIX ?? 'test' };
     if (json) {
-        process.stdout.write(JSON.stringify({ kind: 'starting', cmd, args: spawnArgs, scope, streamPrefix: testEnv.GAON_STREAM_PREFIX }) + '\n');
+        writeOut(JSON.stringify({ kind: 'starting', cmd, args: spawnArgs, scope, streamPrefix: testEnv.GAON_STREAM_PREFIX }) + '\n');
     }
     else {
-        process.stdout.write(`  gaon test · ${cmd} ${spawnArgs.join(' ')} (scope=${scope})\n`);
+        writeOut(`  gaon test · ${cmd} ${spawnArgs.join(' ')} (scope=${scope})\n`);
     }
     const exitCode = await new Promise((resolvePromise) => {
+        // capture(MCP) 모드는 자식 출력을 파이프로 모아 싱크로 흘린다(도구 응답에 담기).
+        // CLI 경로(미지정)는 vitest 컬러 출력·리포터를 그대로 보이게 stdio 를 상속한다.
         const child = spawn(cmd, spawnArgs, {
             cwd,
             env: testEnv,
-            // vitest 컬러 출력·리포터를 그대로 보여주기 위해 stdio 를 상속한다.
-            stdio: 'inherit',
+            stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit',
         });
+        if (capture) {
+            child.stdout?.on('data', (d) => opts.onOutput(d.toString('utf8')));
+            child.stderr?.on('data', (d) => opts.onOutput(d.toString('utf8')));
+        }
         child.on('error', (err) => {
-            process.stderr.write(`  ✗ gaon test spawn 실패: ${String(err)}\n`);
+            writeErr(`  ✗ gaon test spawn 실패: ${String(err)}\n`);
             resolvePromise(127);
         });
         child.on('close', (code, signal) => {
@@ -195,7 +228,7 @@ export async function runTestCommand(args = [], opts = {}) {
         });
     });
     if (json) {
-        process.stdout.write(JSON.stringify({ kind: 'exited', exitCode }) + '\n');
+        writeOut(JSON.stringify({ kind: 'exited', exitCode }) + '\n');
     }
     return exitCode;
 }

package/dist/db/journal.d.ts

@@ -9,7 +9,14 @@ export interface JournalEntry {
     readonly down_sql: string | null;
     readonly applied_at: Date;
 }
-/** _gaon_migrations 존재 여부. information_schema 조회로 방언 무관. */
+/**
+ * _gaon_migrations 존재 여부. information_schema 조회로 방언 무관.
+ *
+ * count 는 캐스트 없이 뽑는다 — 이전 `count(*)::text` 는 postgres 전용 문법이라
+ * mysql/mariadb 에서 문법 에러를 내며 `gaon db migrate/status/down/reset` 을 전멸시켰다.
+ * pg 는 count 를 bigint(문자열)로, mysql 은 number 로 돌려주므로 `Number()` 로 통일한다
+ * (양 방언 공통 · 결정 268).
+ */
 export declare function journalExists(db: Kysely<any>): Promise<boolean>;
 /**
  * _gaon_migrations 를 만든다(존재하면 no-op). id/kind/applied_at/db_key/

package/dist/db/journal.js

@@ -9,10 +9,17 @@
 // 마이그레이션은 커넥션별로 돈다(§4.5) — 원장도 커넥션 DB 마다 따로 존재한다.
 import { sql } from 'kysely';
 import { MIGRATIONS_TABLE } from '@gaonjs/data';
-/** _gaon_migrations 존재 여부. information_schema 조회로 방언 무관. */
+/**
+ * _gaon_migrations 존재 여부. information_schema 조회로 방언 무관.
+ *
+ * count 는 캐스트 없이 뽑는다 — 이전 `count(*)::text` 는 postgres 전용 문법이라
+ * mysql/mariadb 에서 문법 에러를 내며 `gaon db migrate/status/down/reset` 을 전멸시켰다.
+ * pg 는 count 를 bigint(문자열)로, mysql 은 number 로 돌려주므로 `Number()` 로 통일한다
+ * (양 방언 공통 · 결정 268).
+ */
 export async function journalExists(db) {
     const rows = await sql `
-    select count(*)::text as n
+    select count(*) as n
     from information_schema.tables
     where table_name = ${MIGRATIONS_TABLE}
   `.execute(db);

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { type DevCommandOptions } from "./commands/dev.js";
 import { type ServeCommandOptions } from "./serve.js";
+import { type DbSubcommand, type DbCommandOptions } from "./commands/db.js";
 import { type DoctorRule } from "./doctor.js";
 export { startDev, resolveDevLayout, regenerateGaonOnce, type DevDeps, type DevLayout, type DevApp, type DevEvent, type DevHandle, type RegenDeps, type RegenResult, } from "./dev.js";
 export { runDevCommand, type DevCommandOptions } from "./commands/dev.js";
@@ -72,6 +73,16 @@ export interface ParsedNewArgs {
  * npm 이 프로젝트 이름으로 오인되지 않도록(결정 167 · O-1 근본 fix).
  */
 export declare function parseNewArgs(rest: readonly string[]): ParsedNewArgs;
+/**
+ * `gaon db <sub>` 의 인자를 파싱한다(argv = 전체 · argv[0]='db', argv[1]=sub).
+ *
+ * 방향 토큰 `down` 은 **위치 인자**다 — 값 플래그(`--db`/`--config <값>`)와 불리언
+ * 플래그를 건너뛰고 판별한다. 이전엔 `argv[2] === 'down'` 고정 위치로만 봐서
+ * `gaon db migrate --db X down` 처럼 플래그가 앞서면 down 을 놓치고 정방향 migrate 로
+ * 조용히 반전됐다(파괴 방향 오동작 · 결정 267). 위치로 훑어 순서와 무관하게
+ * 정확히 롤백으로 인식한다.
+ */
+export declare function parseDbArgs(sub: DbSubcommand, argv: readonly string[]): DbCommandOptions;
 /**
  * `--port <값>` 플래그를 읽어 검증한다(serve·dev 공용). 플래그가 없으면
  * undefined(기본 포트 폴백). 플래그는 있는데 값이 없거나(마지막 토큰) 다른

package/dist/index.js

@@ -197,6 +197,42 @@ export function parseNewArgs(rest) {
     }
     return { name, unknownPm: pmRaw === undefined || pmRaw === "" ? undefined : pmRaw };
 }
+/**
+ * `gaon db <sub>` 의 인자를 파싱한다(argv = 전체 · argv[0]='db', argv[1]=sub).
+ *
+ * 방향 토큰 `down` 은 **위치 인자**다 — 값 플래그(`--db`/`--config <값>`)와 불리언
+ * 플래그를 건너뛰고 판별한다. 이전엔 `argv[2] === 'down'` 고정 위치로만 봐서
+ * `gaon db migrate --db X down` 처럼 플래그가 앞서면 down 을 놓치고 정방향 migrate 로
+ * 조용히 반전됐다(파괴 방향 오동작 · 결정 267). 위치로 훑어 순서와 무관하게
+ * 정확히 롤백으로 인식한다.
+ */
+export function parseDbArgs(sub, argv) {
+    const dbIdx = argv.indexOf("--db");
+    const cfgIdx = argv.indexOf("--config");
+    const valueFlags = new Set(["--db", "--config"]);
+    const positionals = [];
+    for (let i = 2; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === undefined)
+            continue;
+        if (valueFlags.has(a)) {
+            i++; // 플래그 값 스킵
+            continue;
+        }
+        if (a.startsWith("--"))
+            continue; // 불리언 플래그
+        positionals.push(a);
+    }
+    return {
+        json: argv.includes("--json"),
+        db: dbIdx >= 0 ? argv[dbIdx + 1] : undefined,
+        config: cfgIdx >= 0 ? argv[cfgIdx + 1] : undefined,
+        yes: argv.includes("--yes"),
+        dryRun: argv.includes("--dry-run"),
+        // `gaon db migrate down` — 위치 인자로 롤백 지시(순서 무관).
+        down: sub === "migrate" && positionals.includes("down"),
+    };
+}
 /**
  * `--port <값>` 플래그를 읽어 검증한다(serve·dev 공용). 플래그가 없으면
  * undefined(기본 포트 폴백). 플래그는 있는데 값이 없거나(마지막 토큰) 다른
@@ -447,17 +483,7 @@ export function runCli(argv, opts = {}) {
             process.exitCode = 1;
             return;
         }
-        const dbIdx = argv.indexOf("--db");
-        const cfgIdx = argv.indexOf("--config");
-        const dbOpts = {
-            json: argv.includes("--json"),
-            db: dbIdx >= 0 ? argv[dbIdx + 1] : undefined,
-            config: cfgIdx >= 0 ? argv[cfgIdx + 1] : undefined,
-            yes: argv.includes("--yes"),
-            dryRun: argv.includes("--dry-run"),
-            // `gaon db migrate down` — 위치 인자로 롤백 지시.
-            down: sub === "migrate" && argv[2] === "down",
-        };
+        const dbOpts = parseDbArgs(sub, argv);
         void runDbCommand(sub, dbOpts)
             .then((code) => {
             process.exitCode = code;
@@ -616,6 +642,18 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
+    // 결정 266: 미지 명령은 로드맵 배너로 조용히 성공(exit 0)하지 않는다 — `gaon serv`·
+    // `gaon migrate` 같은 오타가 성공 종료로 오판되면 CI·AI 가 실패를 못 본다.
+    // argv[0] 가 있으면서 어떤 명령·플래그와도 안 맞으면(플래그는 `-` 접두라
+    // help/version/json 폴백이 처리) 여기서 fail-loud(§7.5.3). 인자 없는 `gaon`
+    // (argv[0] 미존재)은 종전대로 로드맵 배너를 낸다.
+    if (argv[0] !== undefined && !argv[0].startsWith("-")) {
+        process.stderr.write(`  ✗ 알 수 없는 명령: ${argv[0]}\n` +
+            `  → 지원 명령: dev · serve · check · gen · build · doctor · mcp · hub · work · jobs · db · g · new · console · test\n` +
+            `  → 전체 사용법: gaon --help\n`);
+        process.exitCode = 1;
+        return;
+    }
     if (argv.includes("--help") || argv.includes("-h")) {
         process.stdout.write(renderHelp(version) + "\n");
         return;

package/dist/mcp/tools.d.ts

@@ -54,10 +54,14 @@ export declare function getSchemaTool(args: ToolArgs, cwd: string): Promise<Tool
  */
 export declare function runMigrationTool(args: ToolArgs, cwd: string): Promise<ToolResult>;
 /**
- * `run_tests` — 프로젝트 테스트를 실 실행한다(§9 · vitest spawn).
+ * `run_tests` — 프로젝트 테스트를 정본 `gaon test` 하네스로 실행한다(§9).
  *
- * `gaon test` 와 같은 경로를 쓰되, MCP 컨텍스트에서는 stdout 을 파이프로
- * 캡처해서 결과를 도구 응답에 담아 돌려준다(자식이 종료할 때까지 대기).
+ * 결정 270: 이전엔 여기서 `vitest run` 을 **직접 spawn** 해 `gaon test`(runTestCommand)의
+ * 세 가지 필수 거동을 전부 우회했다 — ① `<db>_test` 프로비저닝(결정 111) ② NATS
+ * `GAON_STREAM_PREFIX` 격리(결정 130) ③ 사용자 `test` 스크립트 우선(결정 170). 주석은
+ * "같은 경로" 라 주장했으나 거짓이었다. 이제 runTestCommand 에 위임하고, MCP(stdio
+ * JSON-RPC) 컨텍스트라 자식·프로비저닝 출력을 `onOutput` 싱크로 모아 도구 응답에
+ * 담는다(process.stdout 오염 0 — 트랜스포트 보호).
  *
  * 인자:
  *   { scope?: 'unit'|'integration'|'all', filter?: string }
@@ -65,8 +69,8 @@ export declare function runMigrationTool(args: ToolArgs, cwd: string): Promise<T
  *      filter — vitest 위치 인자(파일 패턴 substring)
  *
  * 반환:
- *   data: { exitCode, scope, filter, output }
- *   text: vitest 자체 출력(사람 UI 그대로)
+ *   data: { ok, exitCode, scope, filter, output }
+ *   text: gaon test 출력(프로비저닝 + vitest · 사람 UI 그대로)
  */
 export declare function runTestsTool(args: ToolArgs, cwd: string): Promise<ToolResult>;
 /**

package/dist/mcp/tools.js

@@ -32,6 +32,7 @@ import { join, resolve as resolvePath } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { registerTsResolve } from '../tsResolve.js';
 import { runDbMigrate } from '../db/migrate.js';
+import { runTestCommand } from '../commands/test.js';
 import { scanSchemaDir, columns } from '@gaonjs/data';
 // ── 유틸 ────────────────────────────────────────────────────
 /** 문자열 옵션 안전 추출. */
@@ -276,10 +277,14 @@ export async function runMigrationTool(args, cwd) {
 }
 // ── 도구 4: run_tests ────────────────────────────────────────
 /**
- * `run_tests` — 프로젝트 테스트를 실 실행한다(§9 · vitest spawn).
+ * `run_tests` — 프로젝트 테스트를 정본 `gaon test` 하네스로 실행한다(§9).
  *
- * `gaon test` 와 같은 경로를 쓰되, MCP 컨텍스트에서는 stdout 을 파이프로
- * 캡처해서 결과를 도구 응답에 담아 돌려준다(자식이 종료할 때까지 대기).
+ * 결정 270: 이전엔 여기서 `vitest run` 을 **직접 spawn** 해 `gaon test`(runTestCommand)의
+ * 세 가지 필수 거동을 전부 우회했다 — ① `<db>_test` 프로비저닝(결정 111) ② NATS
+ * `GAON_STREAM_PREFIX` 격리(결정 130) ③ 사용자 `test` 스크립트 우선(결정 170). 주석은
+ * "같은 경로" 라 주장했으나 거짓이었다. 이제 runTestCommand 에 위임하고, MCP(stdio
+ * JSON-RPC) 컨텍스트라 자식·프로비저닝 출력을 `onOutput` 싱크로 모아 도구 응답에
+ * 담는다(process.stdout 오염 0 — 트랜스포트 보호).
  *
  * 인자:
  *   { scope?: 'unit'|'integration'|'all', filter?: string }
@@ -287,8 +292,8 @@ export async function runMigrationTool(args, cwd) {
  *      filter — vitest 위치 인자(파일 패턴 substring)
  *
  * 반환:
- *   data: { exitCode, scope, filter, output }
- *   text: vitest 자체 출력(사람 UI 그대로)
+ *   data: { ok, exitCode, scope, filter, output }
+ *   text: gaon test 출력(프로비저닝 + vitest · 사람 UI 그대로)
  */
 export async function runTestsTool(args, cwd) {
     const scope = (stringOpt(args, 'scope') ?? 'all');
@@ -296,39 +301,17 @@ export async function runTestsTool(args, cwd) {
     if (!['unit', 'integration', 'all'].includes(scope)) {
         return errorResult(`scope 는 'unit' | 'integration' | 'all' 중 하나여야 합니다. 입력값: '${scope}'`);
     }
-    // scopeArgs 는 test.ts 와 동일 규칙을 재구성한다 — 순환 import 를 피하려고
-    // 여기서 직접 계산한다(관례는 test.ts scopeArgs 와 정합).
-    const scopeExtras = scope === 'unit'
-        ? ['--exclude', '**/*.integration.test.ts']
-        : scope === 'integration'
-            ? ['integration.test']
-            : [];
-    const passthrough = [...scopeExtras, ...(filter ? [filter] : [])];
-    // 실행 경로: 로컬 vitest 바이너리 우선. 없으면 에러 안내.
-    const vitestBin = join(resolvePath(cwd), 'node_modules', '.bin', 'vitest');
-    if (!existsSync(vitestBin)) {
-        return errorResult(`vitest 가 설치돼 있지 않습니다: ${vitestBin}\n` +
-            `→ 프로젝트에서 \`pnpm add -D vitest\` 후 다시 시도하세요.`);
-    }
-    const child = spawn(vitestBin, ['run', ...passthrough], {
+    let output = '';
+    const exitCode = await runTestCommand(filter ? [filter] : [], {
         cwd,
-        env: process.env,
-        stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (d) => {
-        stdout += d.toString('utf8');
-    });
-    child.stderr.on('data', (d) => {
-        stderr += d.toString('utf8');
-    });
-    const exitCode = await new Promise((resolveExit) => {
-        child.on('close', (code) => resolveExit(code ?? 1));
+        scope,
+        json: false,
+        onOutput: (chunk) => {
+            output += chunk;
+        },
     });
-    const output = stdout + (stderr ? `\n[stderr]\n${stderr}` : '');
     return {
-        text: output || `(vitest 출력 없음 · exit ${exitCode})`,
+        text: output || `(gaon test 출력 없음 · exit ${exitCode})`,
         data: {
             ok: exitCode === 0,
             exitCode,

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

@@ -216,7 +216,7 @@ export const posts = table('posts', {
 | `having` | `('count', op, val)` · `('sum'\|'avg'\|'min'\|'max', col, op, val)` | `GroupChain` | groupBy 뒤 **집계값** 필터 (그룹 키 필터는 `where`). `.having('count', '>', 2)` · `.having('sum', 'price', '>=', 1000)` |
 | `distinct` | `()` · `(col \| col[])` | `Chain` · `SelectChain` | 인자 없으면 `SELECT DISTINCT` 전체 행(집계·벌크 쓰기 이어짐), 컬럼을 주면 그 컬럼만 뽑는 `SelectChain`. `distinct().count()` 는 `count(distinct id)` |
 | `withCount` | `(...rels)` | `IncludedChain` | 관계별 개수를 **상관 서브쿼리**로 얹는다 — `withCount('comments')` → 각 Rec 에 `commentsCount: bigint`. 조인이 아니라 행이 안 늘어 `limit` 과 함께 써도 개수가 정확. **hasMany·hasOne·belongsToMany 만**(belongsTo 는 항상 0/1 이라 throw). `include` 와 같은 체인에 실린다(`include('author').withCount('comments')`) |
-| `join` | `(table, 'table.col', 'self.col')` | `JoinChain` | INNER JOIN — **필터·정렬 수단**이고 반환은 **자기 테이블의 Rec**(조인 테이블 컬럼은 안 실림 → 뽑아야 하면 §5 `Post.query()`). 조인 테이블 조건은 한정 이름(`where('users.name', '=', ...)`), 1:N 부풀림은 `distinct()` 로 접는다. `join`/`leftJoin`·`where`·`orderBy`·`distinct`·`select`·`pluck`·`count`·`exists`·`first`·`all` 이어짐 |
+| `join` | `(table, 'table.col', 'self.col')` | `JoinChain` | INNER JOIN — **필터·정렬 수단**이고 반환은 **자기 테이블의 Rec**(조인 테이블 컬럼은 안 실림 → 뽑아야 하면 §5 `Post.query()`). **자기 테이블 컬럼은 한정 없이 그대로** 쓴다 — `t.timestamps()`·`t.id()` 로 양 테이블이 `createdAt`·`id` 를 공유해도 조인 시 자기 테이블로 자동 한정돼 `where('createdAt', ..)` 가 안전하다(ambiguous column 방지). **조인 테이블** 조건만 한정 이름(`where('users.name', '=', ...)`)으로 쓴다. 1:N 부풀림은 `distinct()` 로 접는다. `join`/`leftJoin`·`where`·`orderBy`·`distinct`·`select`·`pluck`·`count`·`exists`·`first`·`all` 이어짐 |
 | `leftJoin` | `(table, 'table.col', 'self.col')` | `JoinChain` | LEFT OUTER JOIN — 짝 없는 자기 행도 남는다. "짝 없는 것만" = `.where('posts.id', 'is null')` |
 
 > 조인 노출은 정본 결정 28 게이트 (f)(원안 = 기각·`Post.query()` 로만)를

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.41.7",
+  "version": "0.42.0",
   "description": "Gaon CLI — 스캐폴딩·제너레이터·마이그레이션·dev/serve/work/hub·doctor·check (bin: gaon)",
   "type": "module",
   "license": "MIT",
@@ -28,12 +28,12 @@
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
     "@gaonjs/async": "0.15.2",
-    "@gaonjs/config": "0.17.6",
+    "@gaonjs/config": "0.17.7",
     "@gaonjs/core": "0.2.4",
-    "@gaonjs/data": "0.17.1",
+    "@gaonjs/data": "0.17.2",
     "@gaonjs/i18n": "0.2.3",
     "@gaonjs/mail": "0.3.1",
-    "@gaonjs/web": "0.20.1"
+    "@gaonjs/web": "0.20.2"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""