@triflux/core 10.0.0-alpha.1

package/scripts/lib/mcp-manifest.mjs

@@ -0,0 +1,79 @@
+// scripts/lib/mcp-manifest.mjs
+// MCP 서버 활성화 매니페스트 — 단일 진실 소스.
+// tfx-setup 위저드가 저장하고, gateway/filter가 참조한다.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+export const MANIFEST_PATH = join(homedir(), '.claude', 'cache', 'mcp-enabled.json');
+
+/** API 키 불필요 — 항상 활성화 */
+export const CORE_SERVERS = Object.freeze(['context7', '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,118 @@
+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/psmux-info.mjs

@@ -0,0 +1,119 @@
+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",
+];
+
+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",
+];
+
+export function formatPsmuxCommandList(commands = PSMUX_INSTALL_COMMANDS, indent = "") {
+  return commands.map((command) => `${indent}${command}`).join("\n");
+}
+
+export function formatPsmuxInstallGuidance(indent = "") {
+  return formatPsmuxCommandList(PSMUX_INSTALL_COMMANDS, indent);
+}
+
+export function formatPsmuxUpdateGuidance(indent = "") {
+  return formatPsmuxCommandList(PSMUX_UPDATE_COMMANDS, 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 || !helpOutput.includes(command),
+    );
+    const missingOptionalCommands = PSMUX_OPTIONAL_COMMANDS.filter(
+      (command) => !helpOutput || !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("  "),
+    };
+  }
+}

package/scripts/lib/remote-spawn-transfer.mjs

@@ -0,0 +1,196 @@
+import { existsSync, readFileSync, statSync } from "fs";
+import { basename, dirname, isAbsolute, resolve } from "path";
+
+const URL_LIKE_RE = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//u;
+const WINDOWS_ABS_RE = /^[a-zA-Z]:[\\/]/u;
+
+function normalizeMarkdownTarget(raw) {
+  const trimmed = String(raw || "").trim();
+  const match = /^<?([^>\s]+)>?(?:\s+["'][^"']*["'])?$/u.exec(trimmed);
+  return match ? match[1] : trimmed;
+}
+
+function sanitizeToken(raw) {
+  let token = String(raw || "").trim();
+  if (!token) return "";
+  token = token.replace(/^[<(]+/u, "").replace(/[)>.,;:!?]+$/u, "").trim();
+  return token;
+}
+
+function isLikelyPathToken(token) {
+  if (!token || URL_LIKE_RE.test(token)) return false;
+  if (token.startsWith("app://") || token.startsWith("plugin://") || token.startsWith("mention://")) return false;
+  if (token === "~") return false;
+
+  const hasPathSeparator = token.includes("/") || token.includes("\\");
+  const hasDotPrefix = token.startsWith("./") || token.startsWith("../") || token.startsWith(".");
+  const isHomeRelative = token.startsWith("~/") || token.startsWith("~\\");
+  const isWindowsAbs = WINDOWS_ABS_RE.test(token);
+  const hasFileLikeSuffix = /\.[a-zA-Z0-9]{1,16}$/u.test(token);
+
+  return hasPathSeparator || hasDotPrefix || isHomeRelative || isWindowsAbs || hasFileLikeSuffix;
+}
+
+export function extractExplicitFileTokens(text) {
+  const content = String(text || "");
+  const candidates = [];
+
+  for (const match of content.matchAll(/\[[^\]]+\]\(([^)\n]+)\)/gu)) {
+    candidates.push(normalizeMarkdownTarget(match[1]));
+  }
+  for (const match of content.matchAll(/`([^`\n]+)`/gu)) {
+    candidates.push(match[1]);
+  }
+  for (const match of content.matchAll(/"([^"\n]+)"/gu)) {
+    candidates.push(match[1]);
+  }
+  for (const match of content.matchAll(/'([^'\n]+)'/gu)) {
+    candidates.push(match[1]);
+  }
+
+  const unique = new Set();
+  for (const raw of candidates) {
+    const token = sanitizeToken(raw);
+    if (!isLikelyPathToken(token)) continue;
+    unique.add(token);
+  }
+
+  return Array.from(unique);
+}
+
+function validateTransferFile(filePath, maxBytes) {
+  if (!existsSync(filePath)) {
+    throw new Error(`referenced file not found: ${filePath}`);
+  }
+  const stats = statSync(filePath);
+  if (!stats.isFile()) {
+    throw new Error(`referenced path is not a file: ${filePath}`);
+  }
+  if (stats.size > maxBytes) {
+    throw new Error(`referenced file too large: ${stats.size} bytes (max ${maxBytes}) for ${filePath}`);
+  }
+  return stats.size;
+}
+
+function resolveReferencePath(token, handoffAbsPath, cwd) {
+  if (WINDOWS_ABS_RE.test(token) || isAbsolute(token)) {
+    return resolve(token);
+  }
+
+  if (token.startsWith("~/") || token.startsWith("~\\")) {
+    if (!process.env.HOME && !process.env.USERPROFILE) {
+      return null;
+    }
+    const homeDir = process.env.HOME || process.env.USERPROFILE;
+    return resolve(homeDir, token.slice(2));
+  }
+
+  const handoffDir = dirname(handoffAbsPath);
+  const primary = resolve(handoffDir, token);
+  if (existsSync(primary)) {
+    return primary;
+  }
+
+  const fallback = resolve(cwd, token);
+  return existsSync(fallback) ? fallback : primary;
+}
+
+function toRemotePath(stageRoot, relativePath) {
+  const root = String(stageRoot).replace(/\\/gu, "/").replace(/\/+$/u, "");
+  const rel = String(relativePath).replace(/\\/gu, "/").replace(/^\/+/, "");
+  return `${root}/${rel}`;
+}
+
+export function buildRemoteTransferPlan(options = {}) {
+  const {
+    cwd = process.cwd(),
+    handoffPath = null,
+    maxBytes,
+    remoteStageRoot,
+    userPrompt = null,
+    maxReferenceFiles = 32,
+  } = options;
+
+  if (!handoffPath) {
+    return {
+      prompt: userPrompt || "",
+      replacements: [],
+      stagedHandoffPath: null,
+      transfers: [],
+    };
+  }
+
+  if (!remoteStageRoot) {
+    throw new Error("remoteStageRoot is required when handoffPath is provided");
+  }
+
+  if (!Number.isFinite(maxBytes) || maxBytes <= 0) {
+    throw new Error("maxBytes must be a positive number");
+  }
+
+  const absoluteHandoffPath = resolve(cwd, handoffPath);
+  validateTransferFile(absoluteHandoffPath, maxBytes);
+  const handoffContent = readFileSync(absoluteHandoffPath, "utf8").trim();
+
+  const stagedHandoffPath = toRemotePath(remoteStageRoot, `handoff/${basename(absoluteHandoffPath)}`);
+  const transfers = [{
+    localPath: absoluteHandoffPath,
+    remotePath: stagedHandoffPath,
+    type: "handoff",
+  }];
+
+  const tokens = extractExplicitFileTokens(handoffContent);
+  if (tokens.length > maxReferenceFiles) {
+    throw new Error(`too many referenced files: ${tokens.length} (max ${maxReferenceFiles})`);
+  }
+
+  const stagedByLocalPath = new Map();
+  const replacements = [];
+  let fileIndex = 0;
+
+  for (const token of tokens) {
+    const resolvedPath = resolveReferencePath(token, absoluteHandoffPath, cwd);
+    validateTransferFile(resolvedPath, maxBytes);
+
+    if (!stagedByLocalPath.has(resolvedPath)) {
+      fileIndex += 1;
+      const stagedPath = toRemotePath(
+        remoteStageRoot,
+        `refs/${String(fileIndex).padStart(2, "0")}-${basename(resolvedPath)}`,
+      );
+      stagedByLocalPath.set(resolvedPath, stagedPath);
+      transfers.push({
+        localPath: resolvedPath,
+        remotePath: stagedPath,
+        type: "reference",
+      });
+    }
+
+    replacements.push({ token, stagedPath: stagedByLocalPath.get(resolvedPath) });
+  }
+
+  const replacementEntries = Array.from(
+    replacements
+      .reduce((map, entry) => map.set(entry.token, entry.stagedPath), new Map())
+      .entries(),
+  ).sort((a, b) => b[0].length - a[0].length);
+
+  let rewrittenHandoff = handoffContent;
+  for (const [token, stagedPath] of replacementEntries) {
+    rewrittenHandoff = rewrittenHandoff.split(token).join(stagedPath);
+  }
+
+  const prefix = `Staged handoff file: ${stagedHandoffPath}`;
+  let prompt = rewrittenHandoff ? `${prefix}\n\n${rewrittenHandoff}` : prefix;
+
+  if (userPrompt) {
+    prompt = `${prompt}\n\n---\n\n${userPrompt}`;
+  }
+
+  return {
+    prompt,
+    replacements: replacementEntries.map(([token, stagedPath]) => ({ stagedPath, token })),
+    stagedHandoffPath,
+    transfers,
+  };
+}