@gaonjs/cli 0.4.0 → 0.5.0

package/dist/commands/check.d.ts

@@ -0,0 +1,31 @@
+export type CheckStep = 'typecheck' | 'vue-tsc' | 'build' | 'doctor';
+export interface CheckCommandOptions {
+    readonly cwd?: string;
+    readonly json?: boolean;
+    /** 지정 시 그 검사 하나만 실행. 나머지는 스킵. */
+    readonly only?: CheckStep;
+    /** true 면 doctor 도 포함. 기본 false. */
+    readonly includeDoctor?: boolean;
+}
+export type CheckStepStatus = 'passed' | 'failed' | 'skipped';
+export interface CheckStepResult {
+    readonly step: CheckStep;
+    readonly status: CheckStepStatus;
+    /** 실행에 쓴 커맨드(디버깅용) — skipped 는 undefined. */
+    readonly command?: string;
+    /** 원본 exit code. skipped/doctor 는 undefined. */
+    readonly exitCode?: number;
+    /** stdout+stderr 합본(사람 UI 에 그대로 출력). skipped 는 짧은 사유. */
+    readonly output?: string;
+}
+export interface CheckReport {
+    readonly ok: boolean;
+    readonly steps: readonly CheckStepResult[];
+}
+/**
+ * `gaon check` 진입점. 각 단계를 순서대로 실행하고, 하나라도 실패하면
+ * exit 1. --only 지정 시 그 단계만 실행. --include-doctor 시 doctor 추가.
+ *
+ * §9 실 인프라 · 목업 X — 실 spawn 으로 검증한다.
+ */
+export declare function runCheckCommand(opts?: CheckCommandOptions): Promise<number>;

package/dist/commands/check.js

@@ -0,0 +1,223 @@
+/**
+ * @gaonjs/cli · `gaon check` — 통합 검증 (M9-G · v0.15 §13.5)
+ *
+ * 배포 · CI · AI 에이전트가 한 번에 신뢰할 수 있는 검사 묶음. 사용자의
+ * package.json 관례를 그대로 재사용한다 — `pnpm typecheck` · `pnpm vue-tsc`
+ * · `pnpm build`. 스크립트가 없으면 폴백으로 로컬 바이너리를 직접 부른다
+ * (`node_modules/.bin/tsc --noEmit` · `node_modules/.bin/vue-tsc --noEmit`
+ * · `pnpm -r build` → `npm run build`).
+ *
+ * The One Way — 하나의 명령이 3(선택 4) 검사를 순서대로 돌린다:
+ *   1) typecheck (pnpm typecheck 또는 tsc --noEmit)
+ *   2) vue-tsc   (pnpm vue-tsc 또는 vue-tsc --noEmit)
+ *   3) build     (pnpm build)
+ *   (4) doctor   (--include-doctor 시 · 코어 재사용)
+ *
+ * 옵션 최소:
+ *   --json                     자동화 · 각 검사의 passed/failed/skipped
+ *   --only <name>              단일 검사만
+ *   --include-doctor           check 안에서 doctor 도 · 기본 off
+ *
+ * exit code: 검사가 하나라도 실패하면 1, 그 외 0. 미리 검사할 대상이
+ * 하나도 없으면(예: 스크립트도 없고 바이너리도 없음) 스킵으로 리포트 —
+ * 우회가 아니라 사용자에게 "설정이 부족하다" 를 명확히 노출.
+ *
+ * §9 실 인프라 — 서브 프로세스 실행은 실 `child_process.spawn` 을 쓴다.
+ * 목업 X.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runDoctorCommand } from '../doctor.js';
+/**
+ * 프로젝트 스크립트 존재 여부. pnpm/npm 어느 쪽이든 `scripts.<name>` 을
+ * 정의해 두면 우선 사용한다.
+ */
+function hasScript(cwd, name) {
+    const pkgPath = join(cwd, 'package.json');
+    if (!existsSync(pkgPath))
+        return false;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return typeof pkg.scripts?.[name] === 'string' && pkg.scripts[name].length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function binExists(cwd, name) {
+    return existsSync(join(cwd, 'node_modules', '.bin', name));
+}
+/**
+ * 단일 서브 프로세스를 spawn 해서 stdout+stderr 를 모으고 exit 코드를
+ * 돌려준다. 실행 실패(파일 없음)는 exit 127 로 매핑.
+ */
+function runSubprocess(cwd, cmd, args) {
+    return new Promise((resolvePromise) => {
+        const child = spawn(cmd, args, { cwd, env: process.env });
+        let output = '';
+        child.stdout.on('data', (b) => (output += b.toString('utf8')));
+        child.stderr.on('data', (b) => (output += b.toString('utf8')));
+        child.on('error', (err) => {
+            resolvePromise({ exitCode: 127, output: output + String(err) });
+        });
+        child.on('close', (code) => {
+            resolvePromise({ exitCode: code ?? 1, output });
+        });
+    });
+}
+/** typecheck · vue-tsc 는 노말 검사 · build 는 산출물 생성. */
+async function runStep(step, cwd) {
+    // 1) 사용자 스크립트가 정의돼 있으면 그걸 쓴다(한 곳에서 관리).
+    const scriptName = step;
+    if (hasScript(cwd, scriptName)) {
+        const cmd = 'pnpm';
+        const args = ['run', scriptName];
+        const { exitCode, output } = await runSubprocess(cwd, cmd, args);
+        return {
+            step,
+            status: exitCode === 0 ? 'passed' : 'failed',
+            command: `${cmd} ${args.join(' ')}`,
+            exitCode,
+            output,
+        };
+    }
+    // 2) 폴백 — 로컬 바이너리를 직접 부른다.
+    if (step === 'typecheck') {
+        // tsc 는 로컬 node_modules 또는 workspace 루트에 있다.
+        const tsconfigPath = join(cwd, 'tsconfig.json');
+        if (!existsSync(tsconfigPath)) {
+            return {
+                step,
+                status: 'skipped',
+                output: `tsconfig.json 이 없어 typecheck 를 건너뜁니다: ${tsconfigPath}\n→ 프로젝트 루트에 tsconfig.json 을 만들거나 package.json 에 "typecheck" 스크립트를 정의하세요.`,
+            };
+        }
+        const tsBin = join(cwd, 'node_modules', 'typescript', 'bin', 'tsc');
+        if (!existsSync(tsBin)) {
+            return {
+                step,
+                status: 'skipped',
+                output: `typescript 가 설치돼 있지 않아 typecheck 를 건너뜁니다.\n→ pnpm add -D typescript 후 다시 실행하세요.`,
+            };
+        }
+        const cmd = process.execPath;
+        const args = [tsBin, '--noEmit', '-p', tsconfigPath];
+        const { exitCode, output } = await runSubprocess(cwd, cmd, args);
+        return {
+            step,
+            status: exitCode === 0 ? 'passed' : 'failed',
+            command: `node tsc --noEmit -p ${tsconfigPath}`,
+            exitCode,
+            output,
+        };
+    }
+    if (step === 'vue-tsc') {
+        // vue-tsc 는 .vue 가 하나라도 있는 프로젝트에서만 의미가 있다 —
+        // 없으면 스킵(설치 안 됐어도 정상).
+        if (!binExists(cwd, 'vue-tsc')) {
+            return {
+                step,
+                status: 'skipped',
+                output: 'vue-tsc 가 설치돼 있지 않아 스킵합니다(.vue 파일이 없으면 정상).',
+            };
+        }
+        const tsconfigPath = join(cwd, 'tsconfig.json');
+        if (!existsSync(tsconfigPath)) {
+            return {
+                step,
+                status: 'skipped',
+                output: 'tsconfig.json 이 없어 vue-tsc 를 건너뜁니다.',
+            };
+        }
+        const cmd = join(cwd, 'node_modules', '.bin', 'vue-tsc');
+        const args = ['--noEmit', '-p', tsconfigPath];
+        const { exitCode, output } = await runSubprocess(cwd, cmd, args);
+        return {
+            step,
+            status: exitCode === 0 ? 'passed' : 'failed',
+            command: `vue-tsc --noEmit -p ${tsconfigPath}`,
+            exitCode,
+            output,
+        };
+    }
+    // build — 사용자 스크립트가 없으면 pnpm -r build 를 최선의 폴백으로 시도.
+    const cmd = 'pnpm';
+    const args = ['-r', 'run', 'build'];
+    const { exitCode, output } = await runSubprocess(cwd, cmd, args);
+    return {
+        step,
+        status: exitCode === 0 ? 'passed' : 'failed',
+        command: `${cmd} ${args.join(' ')}`,
+        exitCode,
+        output,
+    };
+}
+/** doctor 는 이미 있는 명령을 재사용 — cwd 만 넘긴다. json 은 상위에서. */
+async function runDoctorStep(cwd) {
+    try {
+        // runDoctorCommand 는 stdout 에 리포트를 그대로 찍는다. 결과 객체로
+        // 성공/실패를 판단한다.
+        const result = await runDoctorCommand({ cwd, json: false });
+        const failed = !!result.fatal || result.errors.length > 0;
+        return {
+            step: 'doctor',
+            status: failed ? 'failed' : 'passed',
+            command: 'gaon doctor',
+            exitCode: failed ? 1 : 0,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            step: 'doctor',
+            status: 'failed',
+            command: 'gaon doctor',
+            exitCode: 1,
+            output: msg,
+        };
+    }
+}
+/**
+ * `gaon check` 진입점. 각 단계를 순서대로 실행하고, 하나라도 실패하면
+ * exit 1. --only 지정 시 그 단계만 실행. --include-doctor 시 doctor 추가.
+ *
+ * §9 실 인프라 · 목업 X — 실 spawn 으로 검증한다.
+ */
+export async function runCheckCommand(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const json = opts.json ?? false;
+    const only = opts.only;
+    const includeDoctor = opts.includeDoctor ?? false;
+    const steps = only
+        ? [only]
+        : ['typecheck', 'vue-tsc', 'build', ...(includeDoctor ? ['doctor'] : [])];
+    const results = [];
+    for (const step of steps) {
+        if (step === 'doctor') {
+            results.push(await runDoctorStep(cwd));
+        }
+        else {
+            results.push(await runStep(step, cwd));
+        }
+    }
+    const ok = results.every((r) => r.status !== 'failed');
+    const report = { ok, steps: results };
+    if (json) {
+        process.stdout.write(JSON.stringify(report) + '\n');
+    }
+    else {
+        for (const r of results) {
+            const mark = r.status === 'passed' ? '✓' : r.status === 'failed' ? '✗' : '·';
+            process.stdout.write(`  ${mark} ${r.step} — ${r.status}${r.command ? ` (${r.command})` : ''}\n`);
+            if (r.status === 'failed' && r.output) {
+                process.stdout.write(r.output.endsWith('\n') ? r.output : r.output + '\n');
+            }
+            if (r.status === 'skipped' && r.output) {
+                process.stdout.write(`    ${r.output.split('\n').join('\n    ')}\n`);
+            }
+        }
+        process.stdout.write(ok ? '  ▶ gaon check · 통과\n' : '  ✗ gaon check · 실패\n');
+    }
+    return ok ? 0 : 1;
+}

package/dist/commands/console.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @gaonjs/cli · `gaon console` — REPL 진입점 (M9-G · v0.15 §13.5)
+ *
+ * Rails console 스타일 — 프로젝트 컨텍스트(gaon.config.ts + apps/*)를
+ * 로드해 배터리(DB · 모델 · 서비스)가 살아있는 상태로 Node REPL 을 띄운다.
+ * 종료는 REPL 관례대로 `.exit` 또는 Ctrl+C(2회).
+ *
+ * The One Way — 단일 진입점 · 옵션 최소:
+ *   · (기본)         gaon.config.ts 로드 → wireGaon → REPL
+ *   · --no-config    순수 REPL (config 없이 · 프로젝트 밖 실험용)
+ *   · --json         부팅 이벤트만 JSON 라인(자동화 · CI 스모크). REPL 자체는
+ *                    stdin TTY 를 그대로 물려 준다.
+ *
+ * loadDomain 은 domain/models · services 를 REPL 컨텍스트에 노출한다.
+ * `.later()` 로 잡을 스케줄해 볼 수 있게 하기 위해 도메인 잡도 함께 로드한다.
+ *
+ * fail-closed(§7.5.3): config 로드 실패는 stderr 에 수리 안내를 던지고
+ * exit code 1 로 나간다 — 우회 없이 정확한 원인을 노출.
+ */
+import { type REPLServer } from 'node:repl';
+export interface ConsoleCommandOptions {
+    readonly cwd?: string;
+    /** 프로젝트 컨텍스트 로드 없이 순수 REPL. 기본 false. */
+    readonly noConfig?: boolean;
+    /** 부팅 이벤트를 JSON 라인으로 출력. REPL 세션 자체는 사람 UI. */
+    readonly json?: boolean;
+    /**
+     * REPL 서버 팩토리 — 테스트가 stdin/stdout 을 갈아 끼울 수 있게 주입점을
+     * 남긴다. 미주입 시 process.stdin/stdout 을 쓰는 기본 REPL.
+     */
+    readonly replFactory?: () => REPLServer;
+    /** 종료 감지용 signals — 테스트에서 SIGINT 를 주입한다. 기본 process. */
+    readonly signals?: {
+        on(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
+        off(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
+    };
+}
+/**
+ * `gaon console` 진입점.
+ *
+ * --no-config: env 만 로드하고 순수 REPL 을 띄운다.
+ * 기본:        loadDotEnv → loadGaonConfig → wireGaon → loadDomain →
+ *              REPL 컨텍스트에 gaon(wired) · config · apps · models · services
+ *              · domain 을 심고, .exit 대기.
+ */
+export declare function runConsoleCommand(opts?: ConsoleCommandOptions): Promise<void>;

package/dist/commands/console.js

@@ -0,0 +1,129 @@
+/**
+ * @gaonjs/cli · `gaon console` — REPL 진입점 (M9-G · v0.15 §13.5)
+ *
+ * Rails console 스타일 — 프로젝트 컨텍스트(gaon.config.ts + apps/*)를
+ * 로드해 배터리(DB · 모델 · 서비스)가 살아있는 상태로 Node REPL 을 띄운다.
+ * 종료는 REPL 관례대로 `.exit` 또는 Ctrl+C(2회).
+ *
+ * The One Way — 단일 진입점 · 옵션 최소:
+ *   · (기본)         gaon.config.ts 로드 → wireGaon → REPL
+ *   · --no-config    순수 REPL (config 없이 · 프로젝트 밖 실험용)
+ *   · --json         부팅 이벤트만 JSON 라인(자동화 · CI 스모크). REPL 자체는
+ *                    stdin TTY 를 그대로 물려 준다.
+ *
+ * loadDomain 은 domain/models · services 를 REPL 컨텍스트에 노출한다.
+ * `.later()` 로 잡을 스케줄해 볼 수 있게 하기 위해 도메인 잡도 함께 로드한다.
+ *
+ * fail-closed(§7.5.3): config 로드 실패는 stderr 에 수리 안내를 던지고
+ * exit code 1 로 나간다 — 우회 없이 정확한 원인을 노출.
+ */
+import { start as startRepl } from 'node:repl';
+import { loadDotEnv } from '@gaonjs/core';
+import { loadGaonConfig, wireGaon, findConfigPath } from '@gaonjs/config';
+import { registerTsResolve } from '../tsResolve.js';
+import { loadDomain } from '../domain.js';
+function humanEvent(e) {
+    switch (e.kind) {
+        case 'starting':
+            return `  gaon console · 시작 — cwd=${e.cwd}${e.noConfig ? ' · --no-config' : ''}`;
+        case 'loaded': {
+            const cfg = e.configPath ? `config=${e.configPath}` : 'config=(없음 · 기본값)';
+            const apps = e.apps.length ? `apps=[${e.apps.join(', ')}]` : 'apps=(없음)';
+            const d = `domain(jobs=${e.domain.jobs} · listeners=${e.domain.listeners} · mails=${e.domain.mails})`;
+            return `  ▶ 로드됨 — ${cfg} · ${apps} · ${d}`;
+        }
+        case 'ready':
+            return e.noConfig
+                ? '  ▶ REPL 준비 (--no-config · 프로젝트 컨텍스트 없음). .exit 로 종료.'
+                : '  ▶ REPL 준비. 컨텍스트: gaon, config, apps, models, services, domain. .exit 로 종료.';
+        case 'exited':
+            return '  gaon console · 종료';
+    }
+}
+/**
+ * `gaon console` 진입점.
+ *
+ * --no-config: env 만 로드하고 순수 REPL 을 띄운다.
+ * 기본:        loadDotEnv → loadGaonConfig → wireGaon → loadDomain →
+ *              REPL 컨텍스트에 gaon(wired) · config · apps · models · services
+ *              · domain 을 심고, .exit 대기.
+ */
+export async function runConsoleCommand(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const json = opts.json ?? false;
+    const noConfig = opts.noConfig ?? false;
+    const signals = opts.signals ?? process;
+    const emit = (e) => {
+        if (json)
+            process.stdout.write(JSON.stringify(e) + '\n');
+        else
+            process.stdout.write(humanEvent(e) + '\n');
+    };
+    // .ts 상대 import 해석기 — 사용자 gaon.config.ts · domain/* 로드에 필요.
+    registerTsResolve();
+    loadDotEnv(cwd);
+    emit({ kind: 'starting', cwd, noConfig });
+    let wired;
+    let domain;
+    let configPath;
+    const context = {};
+    if (!noConfig) {
+        configPath = findConfigPath(cwd);
+        const config = await loadGaonConfig(cwd);
+        wired = await wireGaon(config, cwd);
+        domain = await loadDomain(cwd);
+        context.gaon = wired;
+        context.config = config;
+        context.apps = wired.apps;
+        context.domain = domain;
+        // 모델·서비스 자동 노출은 사용자 코드 스캔이 필요해 v1 은 domain 요약만
+        // 노출한다(§13.5 M9-G 최소 스코프). 사용자는 컨텍스트에서 필요 파일을
+        // `await import(...)` 로 가져올 수 있다(REPL 은 top-level await 허용).
+        context.models = {};
+        context.services = {};
+        emit({
+            kind: 'loaded',
+            configPath,
+            apps: wired.apps.map((a) => a.name),
+            domain: {
+                jobs: domain.jobs,
+                listeners: domain.listeners,
+                mails: domain.mails,
+            },
+        });
+    }
+    emit({ kind: 'ready', noConfig });
+    // REPL 시작 — 테스트는 replFactory 로 stdin/stdout 을 갈아 끼운다.
+    const repl = opts.replFactory
+        ? opts.replFactory()
+        : startRepl({
+            prompt: noConfig ? 'gaon(no-config)> ' : 'gaon> ',
+            useColors: true,
+            // top-level await 허용 — 배터리 검증용 fetch/DB 조회에 편리.
+            // (Node ≥ 22 에서 안정 지원.)
+            useGlobal: false,
+        });
+    // 컨텍스트를 REPL 에 주입.
+    Object.assign(repl.context, context);
+    // Ctrl+C 로 nudge, 종료는 SIGINT 로 배선 close.
+    await new Promise((resolveExit) => {
+        const done = async () => {
+            signals.off('SIGINT', done);
+            signals.off('SIGTERM', done);
+            if (wired) {
+                try {
+                    await wired.close();
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    process.stderr.write(`  ✗ 종료 중 오류: ${msg}\n`);
+                }
+            }
+            emit({ kind: 'exited' });
+            resolveExit();
+        };
+        repl.on('exit', () => void done());
+        signals.on('SIGINT', () => void done());
+        signals.on('SIGTERM', () => void done());
+    });
+}

package/dist/commands/new.d.ts

@@ -0,0 +1,45 @@
+/** `gaon new` 옵션. 모두 선택적 — 기본값이 The One Way. */
+export interface NewCommandOptions {
+    /** 프로젝트 생성 위치의 부모 폴더. 기본 process.cwd(). */
+    readonly cwd?: string;
+    /** 자동화용 구조화 출력. */
+    readonly json?: boolean;
+    /** 의존성 설치 스킵(테스트·오프라인). */
+    readonly skipInstall?: boolean;
+    /** git init · 첫 커밋 스킵(테스트·기존 git 저장소에 삽입). */
+    readonly skipGit?: boolean;
+    /** 패키지 매니저. 기본 pnpm(모노레포 관례 정합). */
+    readonly packageManager?: 'pnpm' | 'npm' | 'yarn';
+    /**
+     * (테스트 훅) 템플릿의 gaonjs 의존성 버전. 미지정 시 파사드(gaonjs)
+     * 패키지의 실 버전을 자동 조회한다(package.json).
+     */
+    readonly gaonjsVersion?: string;
+}
+/** JSON 리포트(--json). 사람 모드는 콘솔에 사람이 읽는 요약을 출력한다. */
+export interface NewCommandResult {
+    readonly ok: boolean;
+    readonly project: string;
+    readonly path: string;
+    readonly filesCreated: number;
+    readonly install: {
+        readonly ran: boolean;
+        readonly skipped: boolean;
+        readonly packageManager: string;
+        readonly durationMs: number;
+        readonly exitCode: number | null;
+    };
+    readonly git: {
+        readonly ran: boolean;
+        readonly skipped: boolean;
+        readonly initialized: boolean;
+        readonly firstCommit: boolean;
+    };
+    readonly totalMs: number;
+    readonly error?: string;
+}
+/**
+ * `gaon new <name>` 실행. 파일 생성 → pnpm install → git init 순서.
+ * 각 단계는 옵션으로 스킵 가능. 반환값은 프로세스 종료 코드(0=성공).
+ */
+export declare function runNewCommand(name: string, opts?: NewCommandOptions): Promise<number>;