@gaonjs/cli 0.1.5 → 0.1.6

package/dist/hub.d.ts

@@ -0,0 +1,22 @@
+export interface HubCommandOptions {
+    readonly json?: boolean;
+    /** NATS 접속지. 생략 시 GAON_NATS_URL, 그다음 기본(4222). */
+    readonly natsUrl?: string;
+    /** 리스 TTL(ms). 생략 시 env GAON_HUB_TTL_MS, 그다음 허브 기본(5000). */
+    readonly ttlMs?: number;
+    /** 멤버 만료 임계(ms). 생략 시 env GAON_HUB_MEMBER_TIMEOUT_MS. */
+    readonly memberTimeoutMs?: number;
+    /** 만료 스윕 주기(ms). 생략 시 env GAON_HUB_SWEEP_MS. */
+    readonly sweepMs?: number;
+    /** 시그널 등록·해제(테스트 주입). 기본 process. */
+    readonly signals?: {
+        on(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
+        off(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
+    };
+}
+/**
+ * 허브를 띄우고 시그널까지 살아 있게 한다. 반환 프라미스는 종료 시 resolve.
+ * 그레이스풀 종료 시 리더 키를 비워(즉시 승계) 대기 인스턴스가 곧바로
+ * 승격하게 한다.
+ */
+export declare function runHubCommand(opts?: HubCommandOptions): Promise<void>;

package/dist/hub.js

@@ -0,0 +1,82 @@
+/**
+ * @gaonjs/cli · `gaon hub` — 실시간 허브 프로세스 (§7 · M6)
+ *
+ * 운영 프로세스 3종(serve · work · hub) 중 하나. 접속자 목록의 단일
+ * 권위이자 중계다(§7 실시간). NATS 에 붙어 프레즌스 명령을 처리하고
+ * KV 에 영속하며, HA 는 리스 기반 리더 선출로 잡는다(active-standby) —
+ * 여러 인스턴스를 띄워도 리더 하나만 명령을 처리한다.
+ *
+ * 개발 모드는 `gaon dev` 가 허브를 같은 프로세스에 내장 실행하므로,
+ * 이 명령은 운영 배치용이다. 모든 명령과 같이 `--json` 을 제공한다.
+ */
+import { hostname } from 'node:os';
+import { connectNats, runHub } from '@gaonjs/async';
+/** 환경변수를 정수로 파싱(미설정·비정상 시 undefined). */
+function envInt(name) {
+    const raw = process.env[name];
+    if (raw == null || raw === '')
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : undefined;
+}
+function humanEvent(e) {
+    switch (e.kind) {
+        case 'starting':
+            return `  gaon hub · 시작 — ${e.id} (NATS 연결·리더 선출 대기)`;
+        case 'leader':
+            return e.leader
+                ? `  ▶ 리더로 승격 — 프레즌스 명령 처리·KV 권위·델타 중계 시작 (${e.id})`
+                : `  · 대기(standby) — 다른 인스턴스가 리더 (${e.id})`;
+        case 'stopped':
+            return '  gaon hub · 종료';
+    }
+}
+/**
+ * 허브를 띄우고 시그널까지 살아 있게 한다. 반환 프라미스는 종료 시 resolve.
+ * 그레이스풀 종료 시 리더 키를 비워(즉시 승계) 대기 인스턴스가 곧바로
+ * 승격하게 한다.
+ */
+export async function runHubCommand(opts = {}) {
+    const json = opts.json ?? false;
+    const signals = opts.signals ?? process;
+    const id = `${hostname()}#${process.pid}`;
+    const emit = (e) => {
+        if (json)
+            process.stdout.write(JSON.stringify(e) + '\n');
+        else
+            process.stdout.write(humanEvent(e) + '\n');
+    };
+    emit({ kind: 'starting', id });
+    const nats = await connectNats({ servers: opts.natsUrl, name: `hub@${id}` });
+    let hub;
+    try {
+        hub = await runHub({
+            nats,
+            id,
+            // 운영 튜닝: 옵션 > 환경변수 > 허브 기본. 컨테이너 배치에서 헬스체크
+            // 주기에 맞춰 리스 TTL·만료 임계를 조정한다.
+            ttlMs: opts.ttlMs ?? envInt('GAON_HUB_TTL_MS'),
+            memberTimeoutMs: opts.memberTimeoutMs ?? envInt('GAON_HUB_MEMBER_TIMEOUT_MS'),
+            sweepMs: opts.sweepMs ?? envInt('GAON_HUB_SWEEP_MS'),
+            onState: (s) => emit({ kind: 'leader', leader: s.leader, id }),
+        });
+    }
+    catch (err) {
+        await nats.close();
+        throw err;
+    }
+    await new Promise((resolve) => {
+        const stop = () => {
+            signals.off('SIGINT', stop);
+            signals.off('SIGTERM', stop);
+            void (async () => {
+                await hub.stop();
+                await nats.close();
+                emit({ kind: 'stopped' });
+                resolve();
+            })();
+        };
+        signals.on('SIGINT', stop);
+        signals.on('SIGTERM', stop);
+    });
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { runDevCommand, startDev, resolveDevLayout, type DevDeps, type DevLayout, type DevApp, type DevEvent, type DevHandle, type DevCommandOptions, } from "./dev.js";
 export { runCheck, runCheckCommand, type CheckDeps, type CheckResult, type TypecheckResult, type CheckCommandOptions, } from "./check.js";
 export { writeAuthScaffold, authScaffoldFiles, patchRoutes, runGenerateAuthCommand, type AuthScaffoldOptions, type ScaffoldFile, type ScaffoldResult, type GenerateAuthOptions, } from "./generate.js";
+export { runHubCommand, type HubCommandOptions } from "./hub.js";
 export interface RoadmapReport {
     readonly name: "gaon";
     readonly version: string;

package/dist/index.js

@@ -13,9 +13,11 @@ import { MILESTONES, VERSION, HOMEPAGE } from "@gaonjs/core";
 import { runDevCommand } from "./dev.js";
 import { runCheckCommand } from "./check.js";
 import { runGenerateAuthCommand } from "./generate.js";
+import { runHubCommand } from "./hub.js";
 export { runDevCommand, startDev, resolveDevLayout, } from "./dev.js";
 export { runCheck, runCheckCommand, } from "./check.js";
 export { writeAuthScaffold, authScaffoldFiles, patchRoutes, runGenerateAuthCommand, } from "./generate.js";
+export { runHubCommand } from "./hub.js";
 /** `--json` 출력용 구조화 리포트. */
 export function roadmapReport(version = VERSION) {
     return {
@@ -63,6 +65,7 @@ function renderHelp(version = VERSION) {
         "    gaon dev --json    재생성 이벤트를 JSON 으로 출력",
         "    gaon check         .gaon 재생성 후 타입 검사 (CI·AI 정합)",
         "    gaon g auth        인증 스캐폴드 생성 (회원가입·로그인·세션·보호 라우트)",
+        "    gaon hub           실시간 허브 프로세스 (프레즌스 권위·중계 · 리더 선출 HA)",
         "    gaon --json        같은 정보를 JSON 으로 출력",
         "    gaon --version     버전 출력",
         "    gaon --help        이 도움말",
@@ -97,6 +100,16 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
+    // `gaon hub` — 실시간 허브 프로세스(§7 M6). 운영 프로세스 3종 중 하나.
+    // NATS·리더 선출 대기로 프로세스를 살려 두고, SIGINT/SIGTERM 에 그레이스풀 종료.
+    if (argv[0] === "hub") {
+        void runHubCommand({ json: argv.includes("--json") }).catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ gaon hub 실패: ${msg}\n`);
+            process.exitCode = 1;
+        });
+        return;
+    }
     // `gaon g auth` — 인증 스캐폴드 제너레이터(§7 M5). 다른 제너레이터는 후속.
     if (argv[0] === "g" || argv[0] === "generate") {
         if (argv[1] === "auth") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Gaon CLI 구현: 제너레이터·스캐폴딩·로드맵 출력 (M1 스텁)",
   "type": "module",
   "license": "MIT",
@@ -24,9 +24,10 @@
     "README.md"
   ],
   "dependencies": {
+    "@gaonjs/async": "0.2.0",
     "@gaonjs/core": "0.1.3",
-    "@gaonjs/data": "0.2.2",
-    "@gaonjs/web": "0.2.0"
+    "@gaonjs/web": "0.2.1",
+    "@gaonjs/data": "0.2.2"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""