triflux 8.11.2 → 8.12.2

package/scripts/mcp-gateway-integration-test.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+// mcp-gateway-integration-test.mjs — P0 integration test for MCP Gateway
+// Usage: node scripts/mcp-gateway-integration-test.mjs
+
+import { execSync } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPTS_DIR = dirname(fileURLToPath(import.meta.url));
+const START_SCRIPT = join(SCRIPTS_DIR, 'mcp-gateway-start.mjs');
+const CONFIG_SCRIPT = join(SCRIPTS_DIR, 'mcp-gateway-config.mjs');
+
+const HEALTH_TIMEOUT_MS = 3000;
+const STARTUP_WAIT_MS = 12000;
+const POLL_INTERVAL_MS = 500;
+
+const SERVERS = [
+  { name: 'context7',     port: 8100 },
+  { name: 'brave-search', port: 8101 },
+  { name: 'exa',          port: 8102 },
+  { name: 'tavily',       port: 8103 },
+  { name: 'jira',         port: 8104 },
+  { name: 'serena',       port: 8105 },
+  { name: 'notion',       port: 8106 },
+  { name: 'notion-guest', port: 8107 },
+];
+
+// ── utilities ──
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+async function checkHealth(port) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/healthz`, {
+      signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+function runScript(scriptPath, ...args) {
+  execSync(`node "${scriptPath}" ${args.join(' ')}`, {
+    stdio: 'inherit',
+    timeout: 30000,
+    env: { ...process.env, MSYS_NO_PATHCONV: '1' },
+  });
+}
+
+function countSupergateways() {
+  try {
+    // Write the query as a PS1 file to avoid shell quoting issues
+    const ps1 = [
+      `$procs = Get-CimInstance Win32_Process -Filter "Name='node.exe' OR Name='cmd.exe'"`,
+      `$hits = $procs | Where-Object { $_.CommandLine -match 'supergateway' }`,
+      `Write-Output $hits.Count`,
+    ].join('\n');
+    const out = execSync(
+      `powershell -NoProfile -Command "${ps1.replace(/\n/g, '; ')}"`,
+      { encoding: 'utf8', timeout: 10000, stdio: ['pipe', 'pipe', 'ignore'] },
+    );
+    return parseInt(out.trim(), 10) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+// ── result tracking ──
+
+const results = [];
+let passed = 0;
+let failed = 0;
+
+function pass(label) {
+  console.log(`  [PASS] ${label}`);
+  results.push({ label, ok: true });
+  passed++;
+}
+
+function fail(label, detail = '') {
+  const msg = detail ? `${label} — ${detail}` : label;
+  console.log(`  [FAIL] ${msg}`);
+  results.push({ label, ok: false, detail });
+  failed++;
+}
+
+function printSummary() {
+  console.log('\n' + '='.repeat(56));
+  console.log('Integration Test Summary');
+  console.log('='.repeat(56));
+  for (const r of results) {
+    const mark = r.ok ? '\u2713' : '\u2717';
+    const detail = r.detail ? `  (${r.detail})` : '';
+    console.log(`  ${mark} ${r.label}${detail}`);
+  }
+  console.log('='.repeat(56));
+  const total = passed + failed;
+  console.log(`Result: ${passed}/${total} passed, ${failed} failed`);
+  if (failed > 0) {
+    console.log('\n[FAIL] Integration test FAILED');
+    process.exitCode = 1;
+  } else {
+    console.log('\n[PASS] Integration test PASSED');
+  }
+}
+
+// ── main ──
+
+async function main() {
+  console.log('\nMCP Gateway Integration Test');
+  console.log('='.repeat(56));
+
+  // STEP 1: Start gateways
+  console.log('\n[STEP 1] Starting gateways...');
+  try {
+    runScript(START_SCRIPT);
+    pass('Gateway start script ran without error');
+  } catch (err) {
+    fail('Gateway start script', err.message);
+    console.log('\n[ABORT] Cannot continue without gateways running');
+    printSummary();
+    return;
+  }
+
+  // STEP 2: Wait for health checks to pass (up to 12s)
+  console.log('\n[STEP 2] Waiting for health checks (up to 12s)...');
+  const deadline = Date.now() + STARTUP_WAIT_MS;
+  const pending = new Set(SERVERS.map((s) => s.port));
+
+  while (pending.size > 0 && Date.now() < deadline) {
+    await sleep(POLL_INTERVAL_MS);
+    for (const port of [...pending]) {
+      if (await checkHealth(port)) pending.delete(port);
+    }
+  }
+
+  let healthOk = 0;
+  let healthSkipped = 0;
+
+  for (const srv of SERVERS) {
+    const alive = !pending.has(srv.port);
+    if (alive) {
+      console.log(`  [ok]   ${srv.name.padEnd(16)} :${srv.port}`);
+      healthOk++;
+    } else {
+      // Servers that stay down are expected when env vars (API keys) are missing
+      console.log(`  [skip] ${srv.name.padEnd(16)} :${srv.port}  (not running — likely missing env)`);
+      healthSkipped++;
+    }
+  }
+
+  if (healthOk === 0) {
+    fail('Health check — no servers responded', `0/${SERVERS.length} up`);
+  } else {
+    pass(`Health check — ${healthOk} server(s) responding (${healthSkipped} skipped)`);
+  }
+
+  // STEP 3: Switch Claude Code config to SSE
+  console.log('\n[STEP 3] Switching Claude Code config to SSE mode...');
+  try {
+    runScript(CONFIG_SCRIPT, '--enable');
+    pass('Config switch to SSE (--enable)');
+  } catch (err) {
+    fail('Config switch to SSE', err.message);
+  }
+
+  // STEP 4: Verify SSE endpoints respond on each active port
+  console.log('\n[STEP 4] Verifying SSE endpoints (/healthz)...');
+  const sseResults = await Promise.allSettled(
+    SERVERS.map(async (srv) => ({ ...srv, alive: await checkHealth(srv.port) })),
+  );
+
+  let sseOk = 0;
+  for (const r of sseResults) {
+    if (r.status !== 'fulfilled') continue;
+    const { name, port, alive } = r.value;
+    if (alive) {
+      console.log(`  [ok]   ${name.padEnd(16)} :${port}`);
+      sseOk++;
+    } else {
+      console.log(`  [skip] ${name.padEnd(16)} :${port}  (not running)`);
+    }
+  }
+
+  if (sseOk === 0 && healthOk > 0) {
+    fail('SSE endpoint verification — servers went down after config switch');
+  } else if (sseOk > 0) {
+    pass(`SSE endpoint verification — ${sseOk} endpoint(s) healthy`);
+  } else {
+    pass('SSE endpoint verification — no servers running (all skipped due to missing env)');
+  }
+
+  // STEP 5: Restore stdio config
+  console.log('\n[STEP 5] Restoring stdio config...');
+  try {
+    runScript(CONFIG_SCRIPT, '--disable');
+    pass('Config restore to stdio (--disable)');
+  } catch (err) {
+    fail('Config restore to stdio', err.message);
+  }
+
+  // STEP 6: Stop gateways
+  console.log('\n[STEP 6] Stopping gateways...');
+  try {
+    runScript(START_SCRIPT, '--stop');
+    pass('Gateway stop script ran without error');
+  } catch (err) {
+    fail('Gateway stop script', err.message);
+  }
+
+  // STEP 7: Orphan check — brief settle, then verify no supergateway processes remain
+  console.log('\n[STEP 7] Checking for orphan supergateway processes...');
+  await sleep(2000);
+
+  const orphanCount = countSupergateways();
+  if (orphanCount === 0) {
+    pass('No orphan supergateway processes (WMI/tasklist clean)');
+  } else {
+    fail('Orphan processes found', `${orphanCount} supergateway process(es) still running`);
+  }
+
+  printSummary();
+}
+
+main();

package/scripts/mcp-gateway-start.mjs

@@ -57,23 +57,43 @@ function sleep(ms) {
 // ── 시작 ──
 
 function spawnGateway(srv) {
-  // 단일 명령 문자열 — shell: true에서 공백 인자를 올바르게 쿼팅
-  const cmdStr = `npx -y supergateway --stdio "${srv.cmd}" --port ${srv.port} --outputTransport sse --healthEndpoint /healthz`;
-
-  // detached: true → 독립 프로세스 그룹 (부모 종료 후 생존)
-  // shell: true → Windows에서 npx.cmd 해석
-  const child = spawn(cmdStr, [], {
-    detached: true,
-    stdio: 'ignore',
-    shell: true,
-    windowsHide: true,
-    env: process.env,
-  });
-  child.unref();
-  return child.pid;
+  // 임시 .cmd 파일로 quoting 문제 회피
+  const cmdContent = `@echo off\nnpx -y supergateway --stdio "${srv.cmd}" --port ${srv.port} --outputTransport sse --healthEndpoint /healthz --cors "http://localhost"`;
+  const cmdFile = join(tmpdir(), `tfx-sg-${srv.name}.cmd`);
+  writeFileSync(cmdFile, cmdContent);
+
+  // PowerShell Start-Process: Windows Job Object에서 벗어나 부모 종료 후 생존
+  execSync(
+    `powershell -NoProfile -Command "Start-Process -WindowStyle Hidden -FilePath cmd.exe -ArgumentList '/c','${cmdFile.replaceAll("'", "''")}'"`
+  , { stdio: 'ignore', timeout: 10000 });
+}
+
+function ensureFirewallRule() {
+  if (process.platform !== 'win32') return;
+  const ports = SERVERS.map((s) => s.port).join(',');
+  const ruleName = 'TFX-MCP-Gateway-Block-External';
+  try {
+    // 기존 규칙 있으면 스킵
+    const check = execSync(
+      `netsh advfirewall firewall show rule name="${ruleName}" 2>&1`,
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 5000 },
+    );
+    if (check.includes(ruleName)) return;
+  } catch { /* 규칙 없음 — 생성 */ }
+
+  try {
+    execSync(
+      `netsh advfirewall firewall add rule name="${ruleName}" dir=in action=block protocol=tcp localport=${ports} remoteip=any profile=any`,
+      { stdio: 'ignore', timeout: 5000 },
+    );
+    console.log(`[SEC] Firewall rule added: block external access to ports ${ports}`);
+  } catch {
+    console.log(`[SEC] WARNING: Could not add firewall rule — run as admin or manually block ports ${ports}`);
+  }
 }
 
 async function startAll() {
+  ensureFirewallRule();
   const launched = [];
 
   for (const srv of SERVERS) {
@@ -136,8 +156,14 @@ async function startAll() {
 function stopAll() {
   // supergateway + 하위 MCP 프로세스를 포트 기반으로 찾아 종료
   try {
-    const ps = `Get-CimInstance Win32_Process -Filter "Name='node.exe' OR Name='cmd.exe'" | Where-Object { $_.CommandLine -match 'supergateway' } | ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null; Write-Output "[STOP] PID $($_.ProcessId)" }`;
-    const output = execSync(`powershell -NoProfile -Command "${ps}"`, {
+    // temp .ps1 파일로 bash/cmd 쿼팅 충돌 회피
+    const psFile = join(tmpdir(), 'tfx-sg-stop.ps1');
+    writeFileSync(psFile, [
+      `Get-CimInstance Win32_Process -Filter "Name='node.exe' OR Name='cmd.exe'" |`,
+      `  Where-Object { $_.CommandLine -match 'supergateway' } |`,
+      `  ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null; Write-Output "[STOP] PID $($_.ProcessId)" }`,
+    ].join('\n'));
+    const output = execSync(`powershell -NoProfile -ExecutionPolicy Bypass -File "${psFile}"`, {
       encoding: 'utf8',
       timeout: 10000,
       stdio: ['pipe', 'pipe', 'ignore'],

package/scripts/mcp-gateway-start.ps1

@@ -34,27 +34,30 @@ function Test-PortInUse {
 }
 
 function Stop-AllGateways {
-  if (-not (Test-Path $PidFile)) {
-    Write-Host '[gateway] PID file not found — nothing to stop'
-    return
-  }
-  try {
-    $entries = Get-Content $PidFile -Raw | ConvertFrom-Json
-    foreach ($entry in $entries) {
+  # WMI CommandLine 기반 — PID 매니페스트 의존 제거 (F-02)
+  $procs = Get-CimInstance Win32_Process -Filter "Name='node.exe' OR Name='cmd.exe'" |
+    Where-Object { $_.CommandLine -match 'supergateway' }
+
+  if ($procs) {
+    foreach ($p in $procs) {
       try {
-        Stop-Process -Id $entry.pid -Force -ErrorAction SilentlyContinue
-        Write-Host "[STOP] $($entry.name) (PID $($entry.pid))"
+        & taskkill /F /T /PID $p.ProcessId 2>$null | Out-Null
+        Write-Host "[STOP] PID $($p.ProcessId)"
       }
       catch {
-        Write-Host "[SKIP] $($entry.name) (PID $($entry.pid)) — already gone"
+        Write-Host "[SKIP] PID $($p.ProcessId) — already gone"
       }
     }
-    Remove-Item $PidFile -Force -ErrorAction SilentlyContinue
-    Write-Host '[gateway] All gateways stopped'
   }
-  catch {
-    Write-Error "[gateway] Failed to parse PID file: $_"
+  else {
+    Write-Host '[gateway] No supergateway processes found'
+  }
+
+  if (Test-Path $PidFile) {
+    Remove-Item $PidFile -Force -ErrorAction SilentlyContinue
+    Write-Host '[gateway] PID file removed'
   }
+  Write-Host '[gateway] All gateways stopped'
 }
 
 function Start-AllGateways {

package/scripts/mcp-gateway-verify.mjs

@@ -57,7 +57,7 @@ async function main() {
       : `${downCount}/${entries.length} gateways down`,
   );
 
-  process.exit(downCount > 0 ? 1 : 0);
+  process.exitCode = downCount > 0 ? 1 : 0;
 }
 
 main();

package/scripts/preflight-cache.mjs

@@ -1,137 +1,137 @@
-#!/usr/bin/env node
-// scripts/preflight-cache.mjs — 세션 시작 시 preflight 점검 캐싱
-
-import { writeFileSync, mkdirSync, existsSync, readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { homedir } from "node:os";
-import { execSync, spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
-
-const __filename = fileURLToPath(import.meta.url);
-const PKG_ROOT = join(dirname(__filename), "..");
-
-// 동기 대기 (Atomics.wait — Node.js main thread에서 사용 가능)
-const _sab = new Int32Array(new SharedArrayBuffer(4));
-function sleepSync(ms) { Atomics.wait(_sab, 0, 0, ms); }
-
-const CACHE_DIR = join(homedir(), ".claude", "cache");
-const CACHE_FILE = join(CACHE_DIR, "tfx-preflight.json");
-const CACHE_TTL_MS = 30_000; // 30초
-
-function checkHub() {
-  // 1차 시도
-  try {
-    const res = execSync("curl -sf http://127.0.0.1:27888/status", { timeout: 3000, encoding: "utf8", windowsHide: true });
-    const data = JSON.parse(res);
-    return { ok: true, state: data?.hub?.state || "unknown", pid: data?.pid };
-  } catch {}
-
-  // Hub 미응답 → 자동 재시작 시도 (bridge.mjs tryRestartHub 동기 버전)
-  const serverPath = join(PKG_ROOT, "hub", "server.mjs");
-  if (!existsSync(serverPath)) return { ok: false, state: "unreachable", restart: "no_server" };
-
-  try {
-    const child = spawn(process.execPath, [serverPath], {
-      detached: true,
-      stdio: "ignore",
-      windowsHide: true,
-    });
-    child.unref();
-  } catch {
-    return { ok: false, state: "unreachable", restart: "spawn_failed" };
-  }
-
-  // 최대 4초 폴링 (500ms × 8)
-  for (let i = 0; i < 8; i++) {
-    sleepSync(500);
-    try {
-      const res = execSync("curl -sf http://127.0.0.1:27888/status", { timeout: 1000, encoding: "utf8", windowsHide: true });
-      const data = JSON.parse(res);
-      if (data?.hub?.state === "healthy") {
-        return { ok: true, state: "healthy", pid: data?.pid, restarted: true };
-      }
-    } catch {}
-  }
-
-  return { ok: false, state: "unreachable", restart: "timeout" };
-}
-
-function checkRoute() {
-  const routePath = join(homedir(), ".claude", "scripts", "tfx-route.sh");
-  return { ok: existsSync(routePath), path: routePath };
-}
-
-function checkCli(name) {
-  try {
-    const path = execSync(`which ${name} 2>/dev/null || where ${name} 2>nul`, { encoding: "utf8", timeout: 2000, windowsHide: true }).trim();
-    return { ok: !!path, path };
-  } catch {
-    return { ok: false };
-  }
-}
-
-/** Codex auth.json의 JWT에서 chatgpt_plan_type 추출 (pro/plus/free) */
-function detectCodexPlan() {
-  try {
-    const authPath = join(homedir(), ".codex", "auth.json");
-    if (!existsSync(authPath)) return { plan: "unknown", source: "no_auth" };
-    const auth = JSON.parse(readFileSync(authPath, "utf8"));
-    if (auth.auth_mode !== "chatgpt") return { plan: "api", source: "api_key" };
-    const token = auth.tokens?.id_token || auth.tokens?.access_token;
-    if (!token) return { plan: "unknown", source: "no_token" };
-    // JWT payload = 2번째 파트, base64url 디코딩
-    const payload = JSON.parse(Buffer.from(token.split(".")[1], "base64url").toString());
-    const plan = payload?.["https://api.openai.com/auth"]?.chatgpt_plan_type || "unknown";
-    return { plan, source: "jwt" };
-  } catch {
-    return { plan: "unknown", source: "error" };
-  }
-}
-
-function runPreflight() {
-  const result = {
-    timestamp: Date.now(),
-    hub: checkHub(),
-    route: checkRoute(),
-    codex: checkCli("codex"),
-    gemini: checkCli("gemini"),
-    codex_plan: detectCodexPlan(),
-    ok: false,
-  };
-  result.ok = result.hub.ok && result.route.ok;
-
-  // CLI 가용성 → available_agents (triage에서 참조)
-  const agents = [];
-  if (result.codex.ok) agents.push("codex");
-  if (result.gemini.ok) agents.push("gemini");
-  agents.push("claude"); // claude는 항상 가용
-  result.available_agents = agents;
-
-  return result;
-}
-
-// 캐시 읽기 (TTL 검증 포함)
-export function readPreflightCache() {
-  try {
-    const data = JSON.parse(readFileSync(CACHE_FILE, "utf8"));
-    if (Date.now() - data.timestamp < CACHE_TTL_MS) return data;
-  } catch {}
-  return null;
-}
-
-// 메인 실행
-if (process.argv[1]?.endsWith("preflight-cache.mjs")) {
-  const result = runPreflight();
-  mkdirSync(CACHE_DIR, { recursive: true });
-  writeFileSync(CACHE_FILE, JSON.stringify(result, null, 2));
-  // 간결 출력 (hook stdout)
-  const summary = result.ok ? "preflight: ok" : "preflight: FAIL";
-  const details = [];
-  if (!result.hub.ok) details.push("hub:" + result.hub.state);
-  else if (result.hub.restarted) details.push("hub:restarted");
-  if (!result.route.ok) details.push("route:missing");
-  if (result.available_agents.length === 1) details.push("agents:claude-only");
-  console.log(details.length ? `${summary} (${details.join(", ")})` : summary);
-}
-
-export { runPreflight, CACHE_FILE, CACHE_TTL_MS };
+#!/usr/bin/env node
+// scripts/preflight-cache.mjs — 세션 시작 시 preflight 점검 캐싱
+
+import { writeFileSync, mkdirSync, existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { execSync, spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const PKG_ROOT = join(dirname(__filename), "..");
+
+// 동기 대기 (Atomics.wait — Node.js main thread에서 사용 가능)
+const _sab = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms) { Atomics.wait(_sab, 0, 0, ms); }
+
+const CACHE_DIR = join(homedir(), ".claude", "cache");
+const CACHE_FILE = join(CACHE_DIR, "tfx-preflight.json");
+const CACHE_TTL_MS = 30_000; // 30초
+
+function checkHub() {
+  // 1차 시도
+  try {
+    const res = execSync("curl -sf http://127.0.0.1:27888/status", { timeout: 3000, encoding: "utf8", windowsHide: true });
+    const data = JSON.parse(res);
+    return { ok: true, state: data?.hub?.state || "unknown", pid: data?.pid };
+  } catch {}
+
+  // Hub 미응답 → 자동 재시작 시도 (bridge.mjs tryRestartHub 동기 버전)
+  const serverPath = join(PKG_ROOT, "hub", "server.mjs");
+  if (!existsSync(serverPath)) return { ok: false, state: "unreachable", restart: "no_server" };
+
+  try {
+    const child = spawn(process.execPath, [serverPath], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    child.unref();
+  } catch {
+    return { ok: false, state: "unreachable", restart: "spawn_failed" };
+  }
+
+  // 최대 4초 폴링 (500ms × 8)
+  for (let i = 0; i < 8; i++) {
+    sleepSync(500);
+    try {
+      const res = execSync("curl -sf http://127.0.0.1:27888/status", { timeout: 1000, encoding: "utf8", windowsHide: true });
+      const data = JSON.parse(res);
+      if (data?.hub?.state === "healthy") {
+        return { ok: true, state: "healthy", pid: data?.pid, restarted: true };
+      }
+    } catch {}
+  }
+
+  return { ok: false, state: "unreachable", restart: "timeout" };
+}
+
+function checkRoute() {
+  const routePath = join(homedir(), ".claude", "scripts", "tfx-route.sh");
+  return { ok: existsSync(routePath), path: routePath };
+}
+
+function checkCli(name) {
+  try {
+    const path = execSync(`which ${name} 2>/dev/null || where ${name} 2>nul`, { encoding: "utf8", timeout: 2000, windowsHide: true }).trim();
+    return { ok: !!path, path };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/** Codex auth.json의 JWT에서 chatgpt_plan_type 추출 (pro/plus/free) */
+function detectCodexPlan() {
+  try {
+    const authPath = join(homedir(), ".codex", "auth.json");
+    if (!existsSync(authPath)) return { plan: "unknown", source: "no_auth" };
+    const auth = JSON.parse(readFileSync(authPath, "utf8"));
+    if (auth.auth_mode !== "chatgpt") return { plan: "api", source: "api_key" };
+    const token = auth.tokens?.id_token || auth.tokens?.access_token;
+    if (!token) return { plan: "unknown", source: "no_token" };
+    // JWT payload = 2번째 파트, base64url 디코딩
+    const payload = JSON.parse(Buffer.from(token.split(".")[1], "base64url").toString());
+    const plan = payload?.["https://api.openai.com/auth"]?.chatgpt_plan_type || "unknown";
+    return { plan, source: "jwt" };
+  } catch {
+    return { plan: "unknown", source: "error" };
+  }
+}
+
+function runPreflight() {
+  const result = {
+    timestamp: Date.now(),
+    hub: checkHub(),
+    route: checkRoute(),
+    codex: checkCli("codex"),
+    gemini: checkCli("gemini"),
+    codex_plan: detectCodexPlan(),
+    ok: false,
+  };
+  result.ok = result.hub.ok && result.route.ok;
+
+  // CLI 가용성 → available_agents (triage에서 참조)
+  const agents = [];
+  if (result.codex.ok) agents.push("codex");
+  if (result.gemini.ok) agents.push("gemini");
+  agents.push("claude"); // claude는 항상 가용
+  result.available_agents = agents;
+
+  return result;
+}
+
+// 캐시 읽기 (TTL 검증 포함)
+export function readPreflightCache() {
+  try {
+    const data = JSON.parse(readFileSync(CACHE_FILE, "utf8"));
+    if (Date.now() - data.timestamp < CACHE_TTL_MS) return data;
+  } catch {}
+  return null;
+}
+
+// 메인 실행
+if (process.argv[1]?.endsWith("preflight-cache.mjs")) {
+  const result = runPreflight();
+  mkdirSync(CACHE_DIR, { recursive: true });
+  writeFileSync(CACHE_FILE, JSON.stringify(result, null, 2));
+  // 간결 출력 (hook stdout)
+  const summary = result.ok ? "preflight: ok" : "preflight: FAIL";
+  const details = [];
+  if (!result.hub.ok) details.push("hub:" + result.hub.state);
+  else if (result.hub.restarted) details.push("hub:restarted");
+  if (!result.route.ok) details.push("route:missing");
+  if (result.available_agents.length === 1) details.push("agents:claude-only");
+  console.log(details.length ? `${summary} (${details.join(", ")})` : summary);
+}
+
+export { runPreflight, CACHE_FILE, CACHE_TTL_MS };