triflux 10.0.0-alpha.1 → 10.0.0-alpha.2

package/bin/triflux.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // triflux CLI — setup, doctor, version
 import { copyFileSync, existsSync, readFileSync, readSync, writeFileSync, mkdirSync, chmodSync, readdirSync, unlinkSync, statSync, openSync, closeSync } from "fs";
-import { join, dirname, basename } from "path";
+import { join, dirname, basename, resolve } from "path";
 import { homedir, tmpdir } from "os";
 import { execSync, execFileSync, spawn } from "child_process";
 import { fileURLToPath } from "url";
@@ -11,14 +11,17 @@ import { detectMultiplexer, getSessionAttachedCount, killSession, listSessions,
 import { forceCleanupTeam } from "../hub/team/nativeProxy.mjs";
 import { cleanupStaleOmcTeams, inspectStaleOmcTeams } from "../hub/team/staleState.mjs";
 import { getPipelineStateDbPath } from "../hub/pipeline/state.mjs";
+import { serializeHandoff } from "../scripts/lib/handoff.mjs";
 import { ensureGeminiProfiles } from "../scripts/lib/gemini-profiles.mjs";
 import { probePsmuxSupport, formatPsmuxInstallGuidance, formatPsmuxUpdateGuidance } from "../scripts/lib/psmux-info.mjs";
 import {
   addRegistryServer,
+  createDefaultRegistry,
   inspectRegistry,
   inspectRegistryStatus,
   removeRegistryServer,
   removeServerFromTargets,
+  saveRegistry,
   syncRegistryTargets,
 } from "../scripts/lib/mcp-guard-engine.mjs";
 import {
@@ -28,7 +31,13 @@ import {
   extractManagedHookFilename, getManagedRegistryHooks, ensureHooksInSettings,
   ensureCodexHubServerConfig,
 } from "../scripts/setup.mjs";
+import {
+  ensureGlobalClaudeRoutingSection,
+  ensureTfxSection,
+  getLatestRoutingTable,
+} from "../scripts/claudemd-sync.mjs";
 import { cleanupTmpFiles } from "../scripts/tmp-cleanup.mjs";
+import { checkNetworkAvailability, validateRuntimeCachePaths } from "../hub/lib/cache-guard.mjs";
 
 const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const CLAUDE_DIR = join(homedir(), ".claude");
@@ -98,6 +107,17 @@ const CLI_COMMAND_SCHEMAS = Object.freeze({
       { name: "--json", type: "boolean", description: "버전 정보를 JSON으로 출력" },
     ],
   },
+  handoff: {
+    usage: "tfx handoff [--target local|remote] [--decision <text>] [--decision-file <path>] [--output <path>] [--json]",
+    description: "현재 작업 컨텍스트를 세션 핸드오프 프롬프트로 직렬화",
+    options: [
+      { name: "--target", type: "string", description: "주입 대상 (local|remote, 기본값 remote)" },
+      { name: "--decision", type: "string", description: "핸드오프 결정사항 (반복 지정 가능)" },
+      { name: "--decision-file", type: "string", description: "결정사항 파일 (라인/불릿 단위)" },
+      { name: "--output", type: "string", description: "생성한 핸드오프 프롬프트 저장 경로" },
+      { name: "--json", type: "boolean", description: "핸드오프 결과를 JSON으로 출력" },
+    ],
+  },
   list: {
     usage: "tfx list [--json]",
     description: "패키지 스킬과 사용자 스킬 목록 표시",
@@ -522,6 +542,26 @@ function describeSyncAction(src, dst, label) {
   };
 }
 
+function syncClaudeRoutingSectionsForCli() {
+  try {
+    const routingTable = getLatestRoutingTable();
+    return [
+      ensureTfxSection(join(PKG_ROOT, "CLAUDE.md"), routingTable),
+      ensureGlobalClaudeRoutingSection(CLAUDE_DIR),
+    ];
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : "routing_sync_failed";
+    return [{ action: "unchanged", path: join(PKG_ROOT, "CLAUDE.md"), skipped: true, reason }];
+  }
+}
+
+function getClaudeRoutingSyncSummary(results) {
+  return results.reduce((summary, result) => ({
+    changed: summary.changed + (result.action === "created" || result.action === "updated" ? 1 : 0),
+    skipped: summary.skipped + (result.skipped ? 1 : 0),
+  }), { changed: 0, skipped: 0 });
+}
+
 // ── 크로스 셸 진단 ──
 
 function checkCliCrossShell(cmd, installHint) {
@@ -691,7 +731,7 @@ function buildSetupDryRunPlan() {
 }
 
 function cmdSetup(options = {}) {
-  const { dryRun = false, overrideVersion } = options;
+  const { dryRun = false, overrideVersion, skipClaudeMdSync = false } = options;
   if (dryRun) {
     printJson(buildSetupDryRunPlan());
     return;
@@ -781,6 +821,21 @@ function cmdSetup(options = {}) {
   // ── 결과 추적 ──
   const summary = [];
 
+  if (!skipClaudeMdSync) {
+    const claudeRoutingResults = syncClaudeRoutingSectionsForCli();
+    const claudeRoutingSummary = getClaudeRoutingSyncSummary(claudeRoutingResults);
+    if (claudeRoutingSummary.changed > 0) {
+      ok(`CLAUDE.md 라우팅: ${claudeRoutingSummary.changed}개 파일 반영`);
+      summary.push({ item: "CLAUDE.md 라우팅", status: "✅", detail: `${claudeRoutingSummary.changed}개 파일 반영` });
+    } else if (claudeRoutingSummary.skipped > 0) {
+      ok("CLAUDE.md 라우팅: 대상 파일 없음 (건너뜀)");
+      summary.push({ item: "CLAUDE.md 라우팅", status: "⏭️", detail: "대상 파일 없음" });
+    } else {
+      ok("CLAUDE.md 라우팅: 최신 상태");
+      summary.push({ item: "CLAUDE.md 라우팅", status: "✅", detail: "최신 상태" });
+    }
+  }
+
   const codexProfileResult = ensureCodexProfiles();
   if (!codexProfileResult.ok) {
     warn(`Codex profiles 설정 실패: ${codexProfileResult.message}`);
@@ -1128,13 +1183,10 @@ function buildMcpStatusRows(statusInfo) {
 }
 
 function ensureValidRegistryState() {
-  const registryState = inspectRegistry();
+  let registryState = inspectRegistry();
   if (!registryState.exists) {
-    throw createCliError(`MCP registry missing: ${registryState.path}`, {
-      exitCode: EXIT_CONFIG_ERROR,
-      reason: "configError",
-      fix: "config/mcp-registry.json을 복원하거나 `tfx mcp add <name> --url <url>`로 다시 생성하세요.",
-    });
+    saveRegistry(createDefaultRegistry());
+    registryState = inspectRegistry();
   }
   if (!registryState.valid) {
     throw createCliError(`MCP registry invalid: ${registryState.errors.join("; ")}`, {
@@ -1335,9 +1387,13 @@ async function cmdDoctor(options = {}) {
         warn(`MCP registry 자동 동기화 실패: ${error.message}`);
       }
     } else if (registryStateForFix.exists) {
-      warn("MCP registry invalid — auto sync 건너뜀");
+      saveRegistry(createDefaultRegistry());
+      report.actions.push({ type: "mcp-registry-reset", status: "ok" });
+      ok("MCP registry 손상 → 기본값으로 재생성됨");
     } else {
-      info("MCP registry 없음 — auto sync 건너뜀");
+      saveRegistry(createDefaultRegistry());
+      report.actions.push({ type: "mcp-registry-create", status: "ok" });
+      ok("MCP registry 없음 → 기본값으로 자동 생성됨");
     }
     console.log(`\n  ${LINE}`);
     info("수정 완료 — 아래 진단 결과를 확인하세요");
@@ -2157,28 +2213,27 @@ async function cmdDoctor(options = {}) {
   // ── MCP 중앙 레지스트리 ──
   section("MCP Registry");
   {
-    const registryState = inspectRegistry();
+    let registryState = inspectRegistry();
     if (!registryState.exists) {
+      saveRegistry(createDefaultRegistry());
+      registryState = inspectRegistry();
       addDoctorCheck(report, {
         name: "mcp-registry",
-        status: "missing",
+        status: "fixed",
         path: registryState.path,
-        fix: "config/mcp-registry.json을 복원하거나 `tfx mcp add <name> --url <url>`를 실행하세요.",
+        action: "기본값으로 자동 생성됨",
       });
-      warn("mcp-registry.json 없음");
-      info(`path: ${registryState.path}`);
-      issues++;
+      ok("mcp-registry.json 없음 → 기본값으로 자동 생성됨");
     } else if (!registryState.valid) {
+      saveRegistry(createDefaultRegistry());
+      registryState = inspectRegistry();
       addDoctorCheck(report, {
         name: "mcp-registry",
-        status: "invalid",
+        status: "fixed",
         path: registryState.path,
-        errors: registryState.errors,
-        fix: "config/mcp-registry.json 구조를 수정하세요.",
+        action: "손상 감지 → 기본값으로 재생성됨",
       });
-      fail("mcp-registry.json invalid");
-      for (const entry of registryState.errors) info(entry);
-      issues++;
+      warn("mcp-registry.json 손상 → 기본값으로 재생성됨");
     } else {
       const statusInfo = inspectRegistryStatus(registryState.registry);
       const invalidConfigs = statusInfo.configs.filter((config) => config.parseError);
@@ -2434,7 +2489,56 @@ async function cmdDoctor(options = {}) {
   });
 }
 
-function cmdUpdate() {
+function normalizeRemoteReachabilityUrl(remoteUrl) {
+  if (!remoteUrl) return null;
+  if (/^https?:\/\//iu.test(remoteUrl)) {
+    try {
+      return new URL(remoteUrl).origin;
+    } catch {
+      return null;
+    }
+  }
+  const scpMatch = /^git@([^:]+):/iu.exec(remoteUrl);
+  if (scpMatch) return `https://${scpMatch[1]}`;
+  if (/^ssh:\/\//iu.test(remoteUrl)) {
+    try {
+      return `https://${new URL(remoteUrl).hostname}`;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function resolveGitUpdateUrl(repoDir) {
+  try {
+    const remoteUrl = execSync("git remote get-url origin", {
+      encoding: "utf8",
+      timeout: 10_000,
+      cwd: repoDir,
+      stdio: ["pipe", "pipe", "ignore"],
+      windowsHide: true,
+    }).trim();
+    return normalizeRemoteReachabilityUrl(remoteUrl);
+  } catch {
+    return null;
+  }
+}
+
+function resolveUpdateTargets({ installMode, pluginPath }) {
+  const repoDir = installMode === "plugin" ? (pluginPath || PKG_ROOT) : PKG_ROOT;
+  const gitUrl = resolveGitUpdateUrl(repoDir);
+
+  if (installMode === "npm-global" || installMode === "npm-local") {
+    return ["https://registry.npmjs.org/triflux"];
+  }
+  if (installMode === "plugin" || installMode === "git-local") {
+    return gitUrl ? [gitUrl] : ["https://github.com"];
+  }
+  return [];
+}
+
+async function cmdUpdate() {
   const isDev = isDevUpdateRequested(NORMALIZED_ARGS);
   const tagLabel = isDev ? ` ${YELLOW}--dev${RESET}` : "";
   console.log(`\n${BOLD}triflux update${RESET}${tagLabel}\n`);
@@ -2490,6 +2594,27 @@ function cmdUpdate() {
 
   info(`검색: ${installMode === "plugin" ? "플러그인" : installMode === "npm-global" ? "npm global" : installMode === "npm-local" ? "npm local" : installMode === "git-local" ? "git 로컬 저장소" : "알 수 없음"} 설치 감지`);
 
+  const networkTargets = resolveUpdateTargets({ installMode, pluginPath });
+  if (networkTargets.length > 0) {
+    const networkStatus = await checkNetworkAvailability(networkTargets);
+    if (!networkStatus.online) {
+      fail(`네트워크 확인 실패: ${networkStatus.unreachable.join(", ")}`);
+      info("네트워크 연결을 확인한 뒤 다시 시도하세요.");
+      return;
+    }
+    ok(`네트워크 확인 완료 (${networkStatus.reachable.join(", ")})`);
+  }
+
+  const cacheValidation = validateRuntimeCachePaths(join(CLAUDE_DIR, "cache"));
+  if (!cacheValidation.ok) {
+    warn(`런타임 캐시 검증 이슈 ${cacheValidation.issues.length}건 발견`);
+    for (const issue of cacheValidation.issues) {
+      info(`${issue.file}: ${issue.error}`);
+    }
+  } else {
+    ok("런타임 캐시 검증 완료");
+  }
+
   // 2. 설치 방식에 따라 업데이트
   const oldVer = PKG.version;
   let updated = false;
@@ -2654,9 +2779,23 @@ function cmdUpdate() {
       }
     }
 
+    // ── Post-update: CLAUDE.md 라우팅 동기화 ──
+    console.log(`\n${CYAN}── CLAUDE.md 라우팅 동기화 ──${RESET}`);
+    {
+      const claudeRoutingResults = syncClaudeRoutingSectionsForCli();
+      const claudeRoutingSummary = getClaudeRoutingSyncSummary(claudeRoutingResults);
+      if (claudeRoutingSummary.changed > 0) {
+        ok(`CLAUDE.md 라우팅 ${claudeRoutingSummary.changed}개 파일 반영`);
+      } else if (claudeRoutingSummary.skipped > 0) {
+        ok("CLAUDE.md 라우팅 대상 파일 없음 (건너뜀)");
+      } else {
+        ok("CLAUDE.md 라우팅 최신 상태");
+      }
+    }
+
     // ── Post-update: 설정 동기화 ──
     console.log(`\n${CYAN}── 설정 동기화 ──${RESET}`);
-    cmdSetup({ fromUpdate: true, overrideVersion: newVer });
+    cmdSetup({ fromUpdate: true, overrideVersion: newVer, skipClaudeMdSync: true });
 
     // ── Post-update: 훅 오케스트레이터 적용 ──
     {
@@ -2783,6 +2922,128 @@ function cmdVersion(options = {}) {
   console.log("");
 }
 
+function cmdHandoff(args = [], options = {}) {
+  const { json = false } = options;
+  const parsed = {
+    target: "remote",
+    decisions: [],
+    decisionFile: null,
+    output: null,
+    cwd: process.cwd(),
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    const next = args[index + 1];
+
+    if (arg === "--target") {
+      if (!next || next.startsWith("-")) {
+        throw createCliError("--target 값이 필요합니다 (local|remote)", {
+          exitCode: EXIT_ARG_ERROR,
+          reason: "argError",
+          fix: "tfx handoff --target remote",
+        });
+      }
+      if (!["local", "remote"].includes(next)) {
+        throw createCliError(`지원하지 않는 --target 값: ${next}`, {
+          exitCode: EXIT_ARG_ERROR,
+          reason: "argError",
+          fix: "tfx handoff --target local|remote",
+        });
+      }
+      parsed.target = next;
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--decision") {
+      if (!next || next.startsWith("-")) {
+        throw createCliError("--decision 값이 필요합니다", {
+          exitCode: EXIT_ARG_ERROR,
+          reason: "argError",
+          fix: "tfx handoff --decision \"결정사항\"",
+        });
+      }
+      parsed.decisions.push(next);
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--decision-file") {
+      if (!next || next.startsWith("-")) {
+        throw createCliError("--decision-file 경로가 필요합니다", {
+          exitCode: EXIT_ARG_ERROR,
+          reason: "argError",
+          fix: "tfx handoff --decision-file .omx/notepad.md",
+        });
+      }
+      parsed.decisionFile = resolve(next);
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--output" || arg === "--out") {
+      if (!next || next.startsWith("-")) {
+        throw createCliError(`${arg} 경로가 필요합니다`, {
+          exitCode: EXIT_ARG_ERROR,
+          reason: "argError",
+          fix: "tfx handoff --output .omx/handoff.md",
+        });
+      }
+      parsed.output = resolve(next);
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--cwd") {
+      if (!next || next.startsWith("-")) {
+        throw createCliError("--cwd 경로가 필요합니다", {
+          exitCode: EXIT_ARG_ERROR,
+          reason: "argError",
+          fix: "tfx handoff --cwd <project-path>",
+        });
+      }
+      parsed.cwd = resolve(next);
+      index += 1;
+      continue;
+    }
+
+    throw createCliError(`알 수 없는 handoff 옵션: ${arg}`, {
+      exitCode: EXIT_ARG_ERROR,
+      reason: "argError",
+      fix: "tfx handoff --target remote --output .omx/handoff.md",
+    });
+  }
+
+  const result = serializeHandoff({
+    target: parsed.target,
+    decisions: parsed.decisions,
+    decisionFile: parsed.decisionFile,
+    cwd: parsed.cwd,
+  });
+
+  if (parsed.output) {
+    const outputDir = dirname(parsed.output);
+    if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
+    writeFileSync(parsed.output, `${result.prompt}\n`, "utf8");
+  }
+
+  if (json) {
+    printJson({
+      handoff: {
+        ...result,
+        ...(parsed.output ? { output: parsed.output } : {}),
+      },
+    });
+    return;
+  }
+
+  console.log(result.prompt);
+  if (parsed.output) {
+    console.log(`\n${DIM}saved:${RESET} ${parsed.output}`);
+  }
+}
+
 function cmdSchema(args = []) {
   const bundle = loadDelegatorSchemaBundle();
   const selector = String(args[0] || "").trim();
@@ -3054,6 +3315,7 @@ ${updateNotice}
     ${WHITE_BRIGHT}tfx update${RESET}     ${GRAY}최신 안정 버전으로 업데이트${RESET}
     ${DIM}  --dev / dev${RESET}   ${GRAY}dev 태그로 업데이트${RESET}
     ${WHITE_BRIGHT}tfx list${RESET}       ${GRAY}설치된 스킬 목록${RESET}
+    ${WHITE_BRIGHT}tfx handoff${RESET}    ${GRAY}현재 컨텍스트를 원격/로컬 핸드오프 프롬프트로 생성${RESET}
     ${WHITE_BRIGHT}tfx schema${RESET}     ${GRAY}CLI/Hub schema JSON 출력${RESET}
     ${WHITE_BRIGHT}tfx hub${RESET}        ${GRAY}MCP 메시지 버스 관리 (start/stop/status)${RESET}
     ${WHITE_BRIGHT}tfx tray${RESET}       ${GRAY}Windows 시스템 트레이 실행${RESET}
@@ -3553,12 +3815,15 @@ async function main() {
       cmdSchema(cmdArgs);
       return;
     case "update":
-      cmdUpdate();
+      await cmdUpdate();
       return;
     case "list":
     case "ls":
       cmdList({ json: JSON_OUTPUT });
       return;
+    case "handoff":
+      cmdHandoff(cmdArgs, { json: JSON_OUTPUT });
+      return;
     case "hub":
       await cmdHub(cmdArgs, { json: JSON_OUTPUT && (cmdArgs[0] || "status") === "status" });
       return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "10.0.0-alpha.1",
+  "version": "10.0.0-alpha.2",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {

package/skills/_templates/base.md

@@ -0,0 +1,9 @@
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+> **Telemetry**
+>
+> - Skill: `{{SKILL_NAME}}`
+> - Description: `{{SKILL_DESCRIPTION}}`
+> - Session: 요청별 식별자를 유지해 단계별 실행 로그를 추적한다.
+> - Errors: 실패 시 원인/복구/재시도 여부를 구조화해 기록한다.

package/skills/_templates/deep.md

@@ -0,0 +1,6 @@
+## Deep Consensus Protocol
+
+1. Planner / Architect / Critic 역할을 분리해 독립적으로 초안을 만든다.
+2. 교차 검토로 충돌 항목을 수집하고 합의 가능한 변경을 우선 반영한다.
+3. 남은 불일치는 근거(리스크/비용/검증 가능성)와 함께 명시한다.
+4. 합의된 결과만 최종 실행 입력으로 승격한다.

package/skills/tfx-auto/SKILL.md

@@ -32,6 +32,14 @@ argument-hint: "<command|task> [args...]"
 > **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
 > 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
 
+> **Telemetry**
+>
+> - Skill: `tfx-auto`
+> - Description: `통합 CLI 오케스트레이터. 커맨드 숏컷(단일) + 자동 분류/분해(병렬) + 수동 병렬. tfx-route.sh 기반. '코드 짜줘', '구현해줘', '만들어줘', '수정해줘', '고쳐줘', 'implement', 'build', 'fix' 같은 구현/수정 요청에 사용. CLI 라우팅이 필요한 모든 작업에 적극 활용.`
+> - Session: 요청별 식별자를 유지해 단계별 실행 로그를 추적한다.
+> - Errors: 실패 시 원인/복구/재시도 여부를 구조화해 기록한다.
+
+
 
 > **MANDATORY RULES**
 >