@triflux/remote 10.1.0 → 10.25.1

package/scripts/lib/mcp-manifest.mjs

@@ -0,0 +1,89 @@
+// scripts/lib/mcp-manifest.mjs
+// MCP 서버 활성화 매니페스트 — 단일 진실 소스.
+// tfx-setup 위저드가 저장하고, gateway/filter가 참조한다.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const MANIFEST_PATH = join(
+  homedir(),
+  ".claude",
+  "cache",
+  "mcp-enabled.json",
+);
+
+/** API 키 불필요 — 항상 활성화 for gateway-managed MCP servers */
+export const CORE_SERVERS = Object.freeze(["serena"]);
+
+/** 검색 MCP — API 키 필요 */
+export const SEARCH_SERVERS = Object.freeze([
+  { name: "brave-search", envVars: ["BRAVE_API_KEY"] },
+  { name: "exa", envVars: ["EXA_API_KEY"] },
+  { name: "tavily", envVars: ["TAVILY_API_KEY"] },
+]);
+
+/** 통합 MCP — API 키 + 추가 설정 필요 */
+export const INTEGRATION_SERVERS = Object.freeze([
+  {
+    name: "jira",
+    envVars: ["JIRA_API_TOKEN", "JIRA_EMAIL", "JIRA_INSTANCE_URL"],
+  },
+  { name: "notion", envVars: ["NOTION_TOKEN"] },
+  { name: "notion-guest", envVars: ["NOTION_TOKEN"] },
+]);
+
+export function readManifest() {
+  if (!existsSync(MANIFEST_PATH)) return null;
+  try {
+    return JSON.parse(readFileSync(MANIFEST_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function writeManifest(enabledServers) {
+  const dir = dirname(MANIFEST_PATH);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const manifest = {
+    version: 1,
+    updatedAt: new Date().toISOString(),
+    enabled: [...new Set([...CORE_SERVERS, ...enabledServers])],
+  };
+  writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2));
+  return manifest;
+}
+
+/**
+ * 매니페스트 기준으로 활성 서버만 필터링.
+ * @param {Array<string|{name:string}>} allServers — 전체 서버 목록
+ * @returns {Array} 활성 서버 목록. 매니페스트 미존재 시 null (레거시 모드).
+ */
+export function filterByManifest(allServers) {
+  const manifest = readManifest();
+  if (!manifest) return null;
+  const enabled = new Set(manifest.enabled || []);
+  for (const core of CORE_SERVERS) enabled.add(core);
+  return allServers.filter((s) =>
+    enabled.has(typeof s === "string" ? s : s.name),
+  );
+}
+
+/**
+ * 단일 서버 활성화 여부 확인.
+ * 매니페스트 미존재 시 true (레거시 호환).
+ */
+export function isServerEnabled(serverName) {
+  const manifest = readManifest();
+  if (!manifest) return true;
+  if (CORE_SERVERS.includes(serverName)) return true;
+  return (manifest.enabled || []).includes(serverName);
+}
+
+/** 특정 서버에 필요한 환경변수 중 누락된 것 반환 */
+export function getMissingEnvVars(serverName) {
+  const all = [...SEARCH_SERVERS, ...INTEGRATION_SERVERS];
+  const entry = all.find((s) => s.name === serverName);
+  if (!entry) return [];
+  return entry.envVars.filter((k) => !process.env[k]);
+}

package/scripts/lib/mcp-server-catalog.mjs

@@ -0,0 +1,355 @@
+export const SEARCH_SERVER_ORDER = Object.freeze([
+  "brave-search",
+  "tavily",
+  "exa",
+]);
+
+export const MCP_SERVER_TOOL_CATALOG = Object.freeze({
+  context7: Object.freeze(["resolve-library-id", "query-docs"]),
+  "brave-search": Object.freeze(["brave_web_search", "brave_news_search"]),
+  exa: Object.freeze(["web_search_exa", "get_code_context_exa"]),
+  tavily: Object.freeze(["tavily_search", "tavily_extract"]),
+  playwright: Object.freeze([
+    "browser_navigate",
+    "browser_navigate_back",
+    "browser_snapshot",
+    "browser_take_screenshot",
+    "browser_wait_for",
+  ]),
+  "sequential-thinking": Object.freeze(["sequentialthinking"]),
+});
+
+export const MCP_SERVER_DOMAIN_TAGS = Object.freeze({
+  context7: Object.freeze(["docs", "reference", "api", "sdk", "library"]),
+  "brave-search": Object.freeze(["web", "search", "news", "current"]),
+  exa: Object.freeze(["code", "repository", "examples", "search"]),
+  tavily: Object.freeze([
+    "research",
+    "search",
+    "news",
+    "verification",
+    "current",
+  ]),
+  playwright: Object.freeze(["browser", "ui", "visual", "e2e"]),
+  "sequential-thinking": Object.freeze([
+    "analysis",
+    "planning",
+    "reasoning",
+    "security",
+    "review",
+  ]),
+});
+
+export const DOMAIN_TAG_KEYWORDS = Object.freeze({
+  docs: Object.freeze([
+    "docs",
+    "documentation",
+    "manual",
+    "guide",
+    "문서",
+    "가이드",
+    "매뉴얼",
+  ]),
+  reference: Object.freeze([
+    "reference",
+    "spec",
+    "schema",
+    "official",
+    "레퍼런스",
+    "공식",
+    "스펙",
+    "스키마",
+  ]),
+  api: Object.freeze([
+    "api",
+    "endpoint",
+    "interface",
+    "sdk",
+    "호출",
+    "엔드포인트",
+  ]),
+  sdk: Object.freeze([
+    "sdk",
+    "library",
+    "package",
+    "framework",
+    "라이브러리",
+    "패키지",
+    "프레임워크",
+  ]),
+  library: Object.freeze([
+    "library",
+    "package",
+    "framework",
+    "module",
+    "라이브러리",
+    "패키지",
+    "모듈",
+  ]),
+  web: Object.freeze([
+    "web",
+    "site",
+    "article",
+    "forum",
+    "blog",
+    "reddit",
+    "웹",
+    "사이트",
+    "기사",
+    "포럼",
+    "블로그",
+  ]),
+  search: Object.freeze([
+    "search",
+    "browse",
+    "lookup",
+    "find",
+    "검색",
+    "조회",
+    "탐색",
+    "찾아",
+  ]),
+  news: Object.freeze([
+    "latest",
+    "recent",
+    "news",
+    "today",
+    "release",
+    "announcement",
+    "최신",
+    "최근",
+    "뉴스",
+    "오늘",
+    "릴리즈",
+    "공지",
+  ]),
+  current: Object.freeze([
+    "current",
+    "status",
+    "pricing",
+    "changelog",
+    "up-to-date",
+    "현재",
+    "상태",
+    "가격",
+    "변경사항",
+  ]),
+  research: Object.freeze([
+    "research",
+    "verify",
+    "fact-check",
+    "investigate",
+    "리서치",
+    "검증",
+    "조사",
+  ]),
+  verification: Object.freeze([
+    "verify",
+    "validation",
+    "fact-check",
+    "audit",
+    "검증",
+    "확인",
+    "감사",
+  ]),
+  code: Object.freeze([
+    "code",
+    "repo",
+    "repository",
+    "source",
+    "implementation",
+    "bug",
+    "fix",
+    "test",
+    "snippet",
+    "cli",
+    "코드",
+    "리포",
+    "저장소",
+    "구현",
+    "버그",
+    "테스트",
+    "예제",
+    "스크립트",
+  ]),
+  repository: Object.freeze([
+    "repo",
+    "repository",
+    "source",
+    "git",
+    "github",
+    "리포",
+    "저장소",
+    "소스",
+  ]),
+  examples: Object.freeze([
+    "example",
+    "examples",
+    "snippet",
+    "sample",
+    "예제",
+    "샘플",
+  ]),
+  browser: Object.freeze([
+    "browser",
+    "page",
+    "dom",
+    "screenshot",
+    "render",
+    "브라우저",
+    "페이지",
+    "스크린샷",
+    "렌더",
+  ]),
+  ui: Object.freeze([
+    "ui",
+    "ux",
+    "layout",
+    "responsive",
+    "css",
+    "html",
+    "디자인",
+    "레이아웃",
+    "반응형",
+  ]),
+  visual: Object.freeze([
+    "visual",
+    "screenshot",
+    "layout",
+    "render",
+    "screen",
+    "화면",
+    "시각",
+    "스크린샷",
+  ]),
+  e2e: Object.freeze([
+    "playwright",
+    "e2e",
+    "click",
+    "navigate",
+    "automation",
+    "playwright",
+    "클릭",
+    "이동",
+    "자동화",
+  ]),
+  analysis: Object.freeze([
+    "analysis",
+    "analyze",
+    "audit",
+    "compare",
+    "root cause",
+    "분석",
+    "검토",
+    "비교",
+    "원인",
+  ]),
+  planning: Object.freeze([
+    "plan",
+    "planning",
+    "strategy",
+    "design",
+    "계획",
+    "전략",
+    "설계",
+  ]),
+  reasoning: Object.freeze([
+    "reason",
+    "reasoning",
+    "think",
+    "critique",
+    "추론",
+    "사고",
+    "비평",
+  ]),
+  security: Object.freeze([
+    "security",
+    "risk",
+    "threat",
+    "vulnerability",
+    "보안",
+    "위험",
+    "취약점",
+  ]),
+  review: Object.freeze(["review", "reviewer", "inspect", "리뷰", "검수"]),
+});
+
+export const SERVER_EXPLICIT_KEYWORDS = Object.freeze({
+  context7: Object.freeze(["context7"]),
+  "brave-search": Object.freeze(["brave", "brave-search"]),
+  exa: Object.freeze(["exa"]),
+  tavily: Object.freeze(["tavily"]),
+  playwright: Object.freeze(["playwright"]),
+  "sequential-thinking": Object.freeze([
+    "sequential-thinking",
+    "sequential thinking",
+  ]),
+});
+
+export function uniqueStrings(values = []) {
+  return [
+    ...new Set(
+      values
+        .filter((value) => typeof value === "string" && value.trim())
+        .map((value) => value.trim()),
+    ),
+  ];
+}
+
+export function inferDomainTagsFromText(text = "") {
+  if (typeof text !== "string" || !text.trim()) return [];
+  const normalized = text.toLocaleLowerCase();
+  const matched = [];
+
+  for (const [tag, keywords] of Object.entries(DOMAIN_TAG_KEYWORDS)) {
+    if (
+      keywords.some((keyword) =>
+        normalized.includes(String(keyword).toLocaleLowerCase()),
+      )
+    ) {
+      matched.push(tag);
+    }
+  }
+
+  return uniqueStrings(matched);
+}
+
+export function getDefaultServerMetadata(serverName = "") {
+  const toolCount = MCP_SERVER_TOOL_CATALOG[serverName]?.length || 0;
+  const domainTags = uniqueStrings([
+    ...(MCP_SERVER_DOMAIN_TAGS[serverName] || []),
+    ...inferDomainTagsFromText(serverName),
+  ]);
+
+  return {
+    tool_count: toolCount,
+    domain_tags: domainTags,
+  };
+}
+
+export function normalizeServerMetadata(serverName = "", metadata = {}) {
+  const fallback = getDefaultServerMetadata(serverName);
+  const toolCount = Number.isFinite(metadata.tool_count)
+    ? Math.max(0, Math.trunc(metadata.tool_count))
+    : fallback.tool_count;
+  const domainTags = uniqueStrings([
+    ...fallback.domain_tags,
+    ...(Array.isArray(metadata.domain_tags) ? metadata.domain_tags : []),
+    ...inferDomainTagsFromText(
+      [
+        serverName,
+        typeof metadata.command === "string" ? metadata.command : "",
+        typeof metadata.url === "string" ? metadata.url : "",
+        ...(Array.isArray(metadata.args) ? metadata.args : []),
+        ...(metadata.env && typeof metadata.env === "object"
+          ? Object.keys(metadata.env)
+          : []),
+      ].join(" "),
+    ),
+  ]);
+
+  return {
+    tool_count: toolCount,
+    domain_tags: domainTags,
+  };
+}

package/scripts/lib/pid.mjs

@@ -0,0 +1,63 @@
+import { appendFileSync, existsSync, readFileSync, rmSync } from "node:fs";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+let treeKill = null;
+try {
+  treeKill = require("tree-kill");
+} catch {
+  treeKill = null;
+}
+
+function defaultIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function defaultKillTree(pid) {
+  return new Promise((resolve) => {
+    if (treeKill) {
+      treeKill(pid, "SIGTERM", () => resolve());
+      return;
+    }
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
+      // Process already exited.
+    }
+    resolve();
+  });
+}
+
+export class PidTracker {
+  constructor(path, options = {}) {
+    this.path = path;
+    this.isAlive = options.isAlive ?? defaultIsAlive;
+    this.killTree = options.killTree ?? defaultKillTree;
+  }
+
+  track(pid) {
+    if (!pid) return;
+    appendFileSync(this.path, `${pid}\n`);
+  }
+
+  list() {
+    if (!existsSync(this.path)) return [];
+    return readFileSync(this.path, "utf8")
+      .split(/\r?\n/)
+      .map((line) => Number(line.trim()))
+      .filter((pid) => Number.isInteger(pid) && pid > 0);
+  }
+
+  async cleanup() {
+    for (const pid of this.list()) {
+      if (!this.isAlive(pid)) continue;
+      await this.killTree(pid);
+    }
+    rmSync(this.path, { force: true });
+  }
+}

package/scripts/lib/process-utils.mjs

@@ -0,0 +1,26 @@
+// scripts/lib/process-utils.mjs
+// 프로세스 관련 공유 유틸리티 (훅 및 lightweight 스크립트용)
+//
+// Note: hub/lib/process-utils.mjs에는 더 포괄적인 orphan cleanup 로직이 있습니다.
+// 이 파일은 단순 alive 체크만 필요한 훅/스크립트용 (상위 의존성 없이 동작).
+
+/**
+ * 주어진 PID의 프로세스가 살아있는지 확인합니다.
+ * - EPERM: 프로세스는 존재하지만 signal 권한 없음 → alive
+ * - ESRCH: 프로세스가 존재하지 않음 → dead
+ * - 기타 에러 (invalid pid 포함): dead로 간주
+ *
+ * @param {number|string} pid
+ * @returns {boolean}
+ */
+export function isProcessAlive(pid) {
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n <= 0) return false;
+  try {
+    process.kill(n, 0);
+    return true;
+  } catch (e) {
+    if (e?.code === "EPERM") return true;
+    return false;
+  }
+}

package/scripts/lib/psmux-info.mjs

@@ -0,0 +1,179 @@
+import { execFileSync } from "node:child_process";
+
+export const PSMUX_RECOMMENDED_VERSION = "3.3.1";
+export const PSMUX_REQUIRED_COMMANDS = [
+  "new-session",
+  "attach-session",
+  "kill-session",
+  "capture-pane",
+];
+
+export const PSMUX_OPTIONAL_COMMANDS = ["detach-client"];
+
+// Windows 패키지 매니저 — winget/scoop/choco 는 Windows 전용
+export const PSMUX_INSTALL_COMMANDS = [
+  "winget install marlocarlo.psmux",
+  "scoop install psmux",
+  "choco install psmux",
+  "cargo install psmux",
+];
+
+export const PSMUX_UPDATE_COMMANDS = [
+  "winget upgrade marlocarlo.psmux",
+  "scoop update psmux",
+  "choco upgrade psmux",
+  "cargo install psmux --force",
+];
+
+// macOS 전용 — brew 가 표준, cargo 는 cross-platform fallback
+export const PSMUX_INSTALL_COMMANDS_DARWIN = [
+  "brew install psmux",
+  "cargo install psmux",
+];
+
+export const PSMUX_UPDATE_COMMANDS_DARWIN = [
+  "brew upgrade psmux",
+  "cargo install psmux --force",
+];
+
+// Linux 전용 — cargo 만 cross-platform 지원, distro 패키지는 미제공
+export const PSMUX_INSTALL_COMMANDS_LINUX = ["cargo install psmux"];
+
+export const PSMUX_UPDATE_COMMANDS_LINUX = ["cargo install psmux --force"];
+
+// PR #258 OS-primary 분기 정책: macOS/Linux 는 tmux 가 POSIX 표준 primary,
+// psmux 는 선택형. native teams fallback (tmux 또는 child process spawn) 으로 동작 가능.
+export const PSMUX_FALLBACK_NOTE_DARWIN =
+  "macOS 에서는 tmux 가 표준 멀티플렉서이며, " +
+  "triflux 는 psmux 없이도 native teams fallback 으로 멀티모델 병렬 실행을 지원합니다.";
+
+export const PSMUX_FALLBACK_NOTE_LINUX =
+  "Linux 에서는 tmux 가 표준 멀티플렉서이며, " +
+  "triflux 는 psmux 없이도 native teams fallback 으로 멀티모델 병렬 실행을 지원합니다.";
+
+export function getPsmuxInstallCommandsFor(platform = process.platform) {
+  if (platform === "darwin") return PSMUX_INSTALL_COMMANDS_DARWIN;
+  if (platform === "linux") return PSMUX_INSTALL_COMMANDS_LINUX;
+  // win32 또는 기타 (BSD 등) → Windows 풀 리스트로 폴백 (변경 전 동작 유지)
+  return PSMUX_INSTALL_COMMANDS;
+}
+
+export function getPsmuxUpdateCommandsFor(platform = process.platform) {
+  if (platform === "darwin") return PSMUX_UPDATE_COMMANDS_DARWIN;
+  if (platform === "linux") return PSMUX_UPDATE_COMMANDS_LINUX;
+  return PSMUX_UPDATE_COMMANDS;
+}
+
+export function getPsmuxFallbackNoteFor(platform = process.platform) {
+  if (platform === "darwin") return PSMUX_FALLBACK_NOTE_DARWIN;
+  if (platform === "linux") return PSMUX_FALLBACK_NOTE_LINUX;
+  return null;
+}
+
+export function formatPsmuxCommandList(
+  commands = PSMUX_INSTALL_COMMANDS,
+  indent = "",
+) {
+  return commands.map((command) => `${indent}${command}`).join("\n");
+}
+
+export function formatPsmuxInstallGuidance(
+  indent = "",
+  platform = process.platform,
+) {
+  const commands = getPsmuxInstallCommandsFor(platform);
+  const list = formatPsmuxCommandList(commands, indent);
+  const note = getPsmuxFallbackNoteFor(platform);
+  return note ? `${list}\n${indent}(${note})` : list;
+}
+
+export function formatPsmuxUpdateGuidance(
+  indent = "",
+  platform = process.platform,
+) {
+  return formatPsmuxCommandList(getPsmuxUpdateCommandsFor(platform), indent);
+}
+
+export function parsePsmuxVersion(output = "") {
+  const match = String(output).match(/psmux\s+v?(\d+\.\d+\.\d+)/i);
+  return match?.[1] || null;
+}
+
+export function compareSemver(a, b) {
+  const left = String(a || "")
+    .split(".")
+    .map((part) => Number.parseInt(part, 10) || 0);
+  const right = String(b || "")
+    .split(".")
+    .map((part) => Number.parseInt(part, 10) || 0);
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] > right[index]) return 1;
+    if (left[index] < right[index]) return -1;
+  }
+  return 0;
+}
+
+export function isRecommendedPsmuxVersion(version) {
+  if (!version) return false;
+  return compareSemver(version, PSMUX_RECOMMENDED_VERSION) >= 0;
+}
+
+export function probePsmuxSupport(options = {}) {
+  const execFileSyncFn = options.execFileSyncFn || execFileSync;
+  const bin = options.bin || "psmux";
+
+  try {
+    const versionOutput = execFileSyncFn(bin, ["-V"], {
+      encoding: "utf8",
+      timeout: 2000,
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+    });
+    const version = parsePsmuxVersion(versionOutput);
+
+    let helpOutput = "";
+    try {
+      helpOutput = execFileSyncFn(bin, ["--help"], {
+        encoding: "utf8",
+        timeout: 2000,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+      });
+    } catch {
+      helpOutput = "";
+    }
+
+    const missingCommands = PSMUX_REQUIRED_COMMANDS.filter(
+      (command) => !helpOutput?.includes(command),
+    );
+    const missingOptionalCommands = PSMUX_OPTIONAL_COMMANDS.filter(
+      (command) => !helpOutput?.includes(command),
+    );
+
+    return {
+      ok: missingCommands.length === 0,
+      installed: true,
+      version,
+      recommendedVersion: PSMUX_RECOMMENDED_VERSION,
+      recommended: isRecommendedPsmuxVersion(version),
+      missingCommands,
+      missingOptionalCommands,
+      hasHelp: helpOutput.length > 0,
+      installHint: formatPsmuxInstallGuidance("  "),
+      updateHint: formatPsmuxUpdateGuidance("  "),
+    };
+  } catch {
+    return {
+      ok: false,
+      installed: false,
+      version: null,
+      recommendedVersion: PSMUX_RECOMMENDED_VERSION,
+      recommended: false,
+      missingCommands: [...PSMUX_REQUIRED_COMMANDS],
+      missingOptionalCommands: [...PSMUX_OPTIONAL_COMMANDS],
+      hasHelp: false,
+      installHint: formatPsmuxInstallGuidance("  "),
+      updateHint: formatPsmuxUpdateGuidance("  "),
+    };
+  }
+}