@triflux/core 10.0.0-alpha.1

package/hooks/agent-route-guard.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// hooks/agent-route-guard.mjs — PreToolUse:Agent 훅
+// 서브에이전트 스폰 시 triflux 컨텍스트를 구조화 JSON으로 주입한다.
+// - subagent_type별 최적 라우팅 가이드
+// - tfx-multi 활성 상태 시 headless dispatch 강제
+// - 프로젝트 컨텍스트 자동 첨부
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const TFX_MULTI_STATE = join(tmpdir(), "tfx-multi-state.json");
+const EXPIRE_MS = 30 * 60 * 1000; // 30분
+
+// 서브에이전트 타입별 라우팅 힌트
+const AGENT_HINTS = {
+  "general-purpose": "범용 에이전트. tfx 스킬이 활성이면 스킬 MD의 라우팅을 우선한다.",
+  Explore: "탐색 전용. 파일 수정 불가. Glob/Grep/Read만 사용.",
+  Plan: "설계 전용. 파일 수정 불가. 구현 계획 반환.",
+  "oh-my-claudecode:executor": "OMC executor. triflux 프로젝트에서는 tfx-auto 라우팅을 우선.",
+  "oh-my-claudecode:code-reviewer": "OMC 리뷰어. 교차 리뷰 시 CLAUDE.md 교차 검증 규칙 준수.",
+  "oh-my-claudecode:architect": "OMC 아키텍트. READ-ONLY.",
+  "oh-my-claudecode:debugger": "OMC 디버거. 근본 원인 분석 집중.",
+  "oh-my-claudecode:test-engineer": "OMC 테스트. npm test 실행 후 결과 반환.",
+};
+
+function readStdin() {
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function getTfxMultiState() {
+  if (!existsSync(TFX_MULTI_STATE)) return null;
+  try {
+    const state = JSON.parse(readFileSync(TFX_MULTI_STATE, "utf8"));
+    if (Date.now() - state.activatedAt > EXPIRE_MS) return null;
+    return state.active ? state : null;
+  } catch {
+    return null;
+  }
+}
+
+function buildContext(agentType, prompt) {
+  const parts = [];
+
+  // 1. tfx-multi 활성 상태 확인
+  const multiState = getTfxMultiState();
+  if (multiState) {
+    parts.push(
+      "[tfx-multi ACTIVE] headless dispatch 모드. " +
+        "CLI 작업은 Bash(tfx-route.sh)를 통해 실행하세요."
+    );
+  }
+
+  // 2. 에이전트 타입별 힌트
+  const hint = AGENT_HINTS[agentType];
+  if (hint) {
+    parts.push(`[Agent:${agentType}] ${hint}`);
+  }
+
+  // 3. 프로젝트 컨텍스트
+  parts.push(
+    "triflux 프로젝트: subagent_type 미지정 시 'general-purpose' 기본. " +
+      "tfx-* 스킬 활성 시 스킬 MD 라우팅 우선."
+  );
+
+  return parts.join("\n");
+}
+
+function main() {
+  const raw = readStdin();
+  if (!raw.trim()) process.exit(0);
+
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+
+  if (input.tool_name !== "Agent") process.exit(0);
+
+  const toolInput = input.tool_input || {};
+  const agentType = toolInput.subagent_type || toolInput.agent || "general-purpose";
+  const prompt = toolInput.prompt || "";
+
+  const context = buildContext(agentType, prompt);
+
+  // 구조화된 hookSpecificOutput 반환
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "allow",
+      additionalContext: context,
+    },
+  };
+
+  process.stdout.write(JSON.stringify(output));
+}
+
+try {
+  main();
+} catch {
+  // 훅 실패 시 블로킹하지 않음
+  process.exit(0);
+}

package/hooks/cross-review-tracker.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// hooks/cross-review-tracker.mjs — PostToolUse:Edit|Write 훅
+//
+// 파일 수정을 추적하여 교차 리뷰 미검증 파일을 감지한다.
+// CLAUDE.md 규칙: "Claude 작성 코드 → Codex 리뷰, Codex 작성 → Claude 리뷰"
+//
+// 동작:
+//   1. Edit/Write 성공 시 수정된 파일 경로를 상태 파일에 누적
+//   2. 일정 수(REVIEW_THRESHOLD) 이상 미검증 파일이 쌓이면 nudge 메시지 주입
+//   3. git commit 전 미검증 파일 경고
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { tmpdir } from "node:os";
+
+const STATE_DIR = join(tmpdir(), "tfx-cross-review");
+const STATE_FILE = join(STATE_DIR, "pending-review.json");
+const REVIEW_THRESHOLD = 5; // 이 수 이상 미검증 파일 → nudge
+const EXPIRE_MS = 60 * 60 * 1000; // 1시간 후 자동 만료
+
+// 코드 파일만 추적 (설정/문서/빌드 산출물 제외)
+const CODE_EXTENSIONS = new Set([
+  ".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx",
+  ".py", ".rs", ".go", ".java", ".c", ".cpp", ".h",
+  ".vue", ".svelte", ".sh", ".bash", ".ps1",
+]);
+
+function isCodeFile(filePath) {
+  if (!filePath) return false;
+  const ext = filePath.slice(filePath.lastIndexOf(".")).toLowerCase();
+  return CODE_EXTENSIONS.has(ext);
+}
+
+function loadState() {
+  if (!existsSync(STATE_FILE)) {
+    return { files: {}, startedAt: Date.now() };
+  }
+  try {
+    const state = JSON.parse(readFileSync(STATE_FILE, "utf8"));
+    // 만료 체크
+    if (Date.now() - state.startedAt > EXPIRE_MS) {
+      return { files: {}, startedAt: Date.now() };
+    }
+    return state;
+  } catch {
+    return { files: {}, startedAt: Date.now() };
+  }
+}
+
+function saveState(state) {
+  mkdirSync(STATE_DIR, { recursive: true });
+  writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
+}
+
+function readStdin() {
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function main() {
+  const raw = readStdin();
+  if (!raw.trim()) process.exit(0);
+
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+
+  const toolName = input.tool_name || "";
+  if (toolName !== "Edit" && toolName !== "Write") process.exit(0);
+
+  const toolInput = input.tool_input || {};
+  const filePath = toolInput.file_path || "";
+
+  if (!filePath || !isCodeFile(filePath)) process.exit(0);
+
+  // 프로젝트 루트 기준 상대 경로
+  const cwd = input.cwd || process.cwd();
+  const relPath = relative(cwd, filePath) || filePath;
+
+  // 상태 갱신: 파일 추가
+  const state = loadState();
+  state.files[relPath] = {
+    tool: toolName,
+    modifiedAt: Date.now(),
+    reviewed: false,
+  };
+  saveState(state);
+
+  // 미검증 파일 수 체크
+  const unreviewed = Object.entries(state.files).filter(
+    ([, v]) => !v.reviewed
+  );
+  const count = unreviewed.length;
+
+  if (count >= REVIEW_THRESHOLD) {
+    // nudge 메시지 주입
+    const fileList = unreviewed
+      .slice(0, 8)
+      .map(([f]) => `  - ${f}`)
+      .join("\n");
+
+    const output = {
+      systemMessage:
+        `[교차 리뷰 nudge] 미검증 코드 파일 ${count}개:\n${fileList}\n` +
+        (count > 8 ? `  ... 외 ${count - 8}개\n` : "") +
+        `커밋 전 교차 리뷰를 권장합니다. (Claude→Codex 또는 Codex→Claude)`,
+    };
+    process.stdout.write(JSON.stringify(output));
+  }
+}
+
+try {
+  main();
+} catch {
+  process.exit(0);
+}

package/hooks/error-context.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+// hooks/error-context.mjs — PostToolUseFailure 훅
+//
+// 도구 실패 시 에러 패턴을 분석하여 해결 힌트를 additionalContext로 주입한다.
+// Claude가 동일 에러를 반복하지 않도록 구체적 가이드를 제공.
+
+import { readFileSync } from "node:fs";
+
+// ── 에러 패턴 → 해결 힌트 매핑 ─────────────────────────────
+const ERROR_HINTS = [
+  // Node.js / npm
+  {
+    pattern: /ENOENT.*no such file or directory/i,
+    hint: "파일/디렉토리가 존재하지 않습니다. 경로를 확인하거나 mkdir -p로 디렉토리를 먼저 생성하세요.",
+  },
+  {
+    pattern: /EACCES.*permission denied/i,
+    hint: "권한 부족. Windows에서는 관리자 권한, Unix에서는 chmod/sudo를 확인하세요.",
+  },
+  {
+    pattern: /EADDRINUSE/i,
+    hint: "포트가 이미 사용 중입니다. lsof -i :{port} 또는 netstat -ano | findstr :{port}로 확인 후 프로세스를 종료하세요.",
+  },
+  {
+    pattern: /ERR_MODULE_NOT_FOUND|Cannot find module/i,
+    hint: "모듈을 찾을 수 없습니다. npm install을 실행하거나, import 경로에 .mjs/.js 확장자를 명시하세요.",
+  },
+  {
+    pattern: /ETARGET|ERR_INVALID_PACKAGE_TARGET/i,
+    hint: "패키지 버전 해석 실패. package.json의 exports 필드 또는 의존성 버전을 확인하세요.",
+  },
+  {
+    pattern: /npm ERR! code E40[134]/i,
+    hint: "npm 인증 오류. npm login 또는 .npmrc 토큰을 확인하세요.",
+  },
+
+  // Git
+  {
+    pattern: /fatal: not a git repository/i,
+    hint: "git 저장소가 아닙니다. git init 또는 올바른 디렉토리로 이동하세요.",
+  },
+  {
+    pattern: /merge conflict|CONFLICT.*Merge/i,
+    hint: "병합 충돌 발생. 충돌 파일을 수동 해결 후 git add + git commit 하세요.",
+  },
+  {
+    pattern: /rejected.*non-fast-forward/i,
+    hint: "원격에 새 커밋이 있습니다. git pull --rebase 후 다시 push하세요.",
+  },
+  {
+    pattern: /fatal: refusing to merge unrelated histories/i,
+    hint: "--allow-unrelated-histories 플래그가 필요할 수 있습니다.",
+  },
+
+  // Python
+  {
+    pattern: /ModuleNotFoundError/i,
+    hint: "Python 모듈 미설치. pip install 또는 가상환경 활성화를 확인하세요.",
+  },
+  {
+    pattern: /SyntaxError.*invalid syntax/i,
+    hint: "Python 문법 오류. Python 버전(2 vs 3) 호환성도 확인하세요.",
+  },
+
+  // Windows 특이
+  {
+    pattern: /is not recognized as an internal or external command/i,
+    hint: "명령어를 찾을 수 없습니다. PATH 환경변수를 확인하거나 절대 경로를 사용하세요.",
+  },
+  {
+    pattern: /execution policy/i,
+    hint: "PowerShell 실행 정책 제한. -ExecutionPolicy Bypass 플래그를 추가하세요.",
+  },
+  {
+    pattern: /The process cannot access the file because it is being used/i,
+    hint: "파일이 다른 프로세스에 의해 잠겨 있습니다. 해당 프로세스를 종료하거나 잠시 후 재시도하세요.",
+  },
+
+  // 일반
+  {
+    pattern: /timeout|timed out|ETIMEDOUT/i,
+    hint: "타임아웃 발생. 네트워크 상태를 확인하거나 timeout 값을 늘리세요.",
+  },
+  {
+    pattern: /out of memory|heap|ENOMEM/i,
+    hint: "메모리 부족. --max-old-space-size를 늘리거나 데이터 크기를 줄이세요.",
+  },
+  {
+    pattern: /ECONNREFUSED/i,
+    hint: "연결 거부. 대상 서버/서비스가 실행 중인지 확인하세요.",
+  },
+];
+
+function readStdin() {
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function findHints(errorText) {
+  const hints = [];
+  for (const rule of ERROR_HINTS) {
+    if (rule.pattern.test(errorText)) {
+      hints.push(rule.hint);
+    }
+  }
+  return hints;
+}
+
+function main() {
+  const raw = readStdin();
+  if (!raw.trim()) process.exit(0);
+
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+
+  // tool_output 또는 error 필드에서 에러 텍스트 추출
+  const errorText = [
+    input.tool_output || "",
+    input.error || "",
+    input.tool_input?.command || "",
+    JSON.stringify(input.tool_result || ""),
+  ].join("\n");
+
+  const hints = findHints(errorText);
+  if (hints.length === 0) process.exit(0);
+
+  const toolName = input.tool_name || "Unknown";
+  const output = {
+    systemMessage:
+      `[error-context] ${toolName} 실패 — 해결 힌트:\n` +
+      hints.map((h) => `  → ${h}`).join("\n"),
+  };
+
+  process.stdout.write(JSON.stringify(output));
+}
+
+try {
+  main();
+} catch {
+  process.exit(0);
+}