triflux 10.0.0 → 10.0.2

package/mesh/mesh-queue.mjs

@@ -0,0 +1,165 @@
+const DEFAULT_MAX_QUEUE_SIZE = 100;
+const DEFAULT_TTL_MS = 0; // 0 = no expiry
+
+/**
+ * Creates a per-agent message queue with TTL and size limits.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.maxQueueSize=100] - Max messages per agent queue
+ * @param {number} [opts.ttlMs=0]         - Message TTL in ms (0 = no expiry)
+ * @returns {object} Queue API
+ */
+export function createMessageQueue(opts = {}) {
+  const {
+    maxQueueSize = DEFAULT_MAX_QUEUE_SIZE,
+    ttlMs = DEFAULT_TTL_MS,
+  } = opts;
+
+  /** @type {Map<string, Array<{ message: object, enqueuedAt: number }>>} */
+  const queues = new Map();
+
+  /**
+   * Returns the queue array for an agent (creates if absent).
+   * @param {string} agentId
+   * @returns {Array}
+   */
+  function getQueue(agentId) {
+    let q = queues.get(agentId);
+    if (!q) {
+      q = [];
+      queues.set(agentId, q);
+    }
+    return q;
+  }
+
+  /**
+   * Removes expired messages from the front of a queue.
+   * @param {Array} q
+   * @param {number} now
+   */
+  function purgeExpired(q, now) {
+    if (ttlMs <= 0) return;
+    while (q.length > 0 && (now - q[0].enqueuedAt) > ttlMs) {
+      q.shift();
+    }
+  }
+
+  /**
+   * Adds a message to the target agent's queue.
+   * If queue exceeds maxQueueSize, the oldest message is dropped.
+   *
+   * @param {string} agentId - Target agent
+   * @param {object} message - Mesh message
+   * @returns {{ queued: boolean, dropped: boolean }}
+   */
+  function enqueue(agentId, message) {
+    if (!agentId || typeof agentId !== "string") {
+      throw new TypeError("agentId must be a non-empty string");
+    }
+    const q = getQueue(agentId);
+    const now = Date.now();
+
+    purgeExpired(q, now);
+
+    let dropped = false;
+    if (q.length >= maxQueueSize) {
+      q.shift();
+      dropped = true;
+    }
+
+    q.push({ message, enqueuedAt: now });
+    return { queued: true, dropped };
+  }
+
+  /**
+   * Removes and returns the next message for an agent.
+   *
+   * @param {string} agentId
+   * @returns {object | null} The message, or null if queue is empty
+   */
+  function dequeue(agentId) {
+    const q = queues.get(agentId);
+    if (!q || q.length === 0) return null;
+
+    const now = Date.now();
+    purgeExpired(q, now);
+
+    if (q.length === 0) return null;
+    return q.shift().message;
+  }
+
+  /**
+   * Returns the next message without removing it.
+   *
+   * @param {string} agentId
+   * @returns {object | null}
+   */
+  function peek(agentId) {
+    const q = queues.get(agentId);
+    if (!q || q.length === 0) return null;
+
+    const now = Date.now();
+    purgeExpired(q, now);
+
+    if (q.length === 0) return null;
+    return q[0].message;
+  }
+
+  /**
+   * Returns the number of (non-expired) messages in an agent's queue.
+   *
+   * @param {string} agentId
+   * @returns {number}
+   */
+  function size(agentId) {
+    const q = queues.get(agentId);
+    if (!q) return 0;
+
+    const now = Date.now();
+    purgeExpired(q, now);
+
+    return q.length;
+  }
+
+  /**
+   * Drains all messages for an agent.
+   *
+   * @param {string} agentId
+   * @returns {object[]} Array of messages
+   */
+  function drain(agentId) {
+    const q = queues.get(agentId);
+    if (!q || q.length === 0) return [];
+
+    const now = Date.now();
+    purgeExpired(q, now);
+
+    const messages = q.map((entry) => entry.message);
+    q.length = 0;
+    return messages;
+  }
+
+  /**
+   * Removes an agent's queue entirely.
+   * @param {string} agentId
+   */
+  function clear(agentId) {
+    queues.delete(agentId);
+  }
+
+  /**
+   * Returns total message count across all agent queues.
+   * @returns {number}
+   */
+  function totalSize() {
+    let total = 0;
+    const now = Date.now();
+    for (const [, q] of queues) {
+      purgeExpired(q, now);
+      total += q.length;
+    }
+    return total;
+  }
+
+  return { enqueue, dequeue, peek, size, drain, clear, totalSize };
+}

package/mesh/mesh-registry.mjs

@@ -0,0 +1,78 @@
+/**
+ * Creates an agent registry for the mesh network.
+ * Agents register with capabilities; registry enables discovery.
+ * @returns {object} Registry API
+ */
+export function createRegistry() {
+  // Map<agentId, AgentInfo>
+  const agents = new Map();
+
+  /**
+   * Registers an agent with the registry.
+   * @param {string} agentId
+   * @param {string[]} capabilities
+   */
+  function register(agentId, capabilities = []) {
+    if (!agentId || typeof agentId !== "string") {
+      throw new TypeError("agentId must be a non-empty string");
+    }
+    if (!Array.isArray(capabilities)) {
+      throw new TypeError("capabilities must be an array");
+    }
+    const info = Object.freeze({
+      agentId,
+      capabilities: Object.freeze([...capabilities]),
+      registeredAt: new Date().toISOString(),
+    });
+    agents.set(agentId, info);
+  }
+
+  /**
+   * Unregisters an agent from the registry.
+   * @param {string} agentId
+   */
+  function unregister(agentId) {
+    agents.delete(agentId);
+  }
+
+  /**
+   * Discovers agents that have a specific capability.
+   * @param {string} capability
+   * @returns {string[]} Array of agentIds
+   */
+  function discover(capability) {
+    const result = [];
+    for (const [agentId, info] of agents) {
+      if (info.capabilities.includes(capability)) {
+        result.push(agentId);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Gets agent info by ID.
+   * @param {string} agentId
+   * @returns {object | null}
+   */
+  function getAgent(agentId) {
+    return agents.get(agentId) ?? null;
+  }
+
+  /**
+   * Lists all registered agents.
+   * @returns {object[]}
+   */
+  function listAll() {
+    return [...agents.values()];
+  }
+
+  /**
+   * Clears all registered agents.
+   */
+  function clear() {
+    agents.clear();
+  }
+
+  return { register, unregister, discover, getAgent, listAll, clear };
+}

package/mesh/mesh-router.mjs

@@ -0,0 +1,76 @@
+import { validate } from "./mesh-protocol.mjs";
+
+/**
+ * Routes a mesh message to target agent(s) based on the `to` field.
+ *
+ * Addressing modes:
+ *   - "agent-id"       → direct delivery (registry lookup)
+ *   - "*"              → broadcast to all registered agents
+ *   - "capability:X"   → discover agents with capability X
+ *
+ * @param {object} message  - A mesh-protocol message
+ * @param {object} registry - A mesh-registry instance
+ * @returns {{ routed: boolean, targets?: string[], reason?: string }}
+ */
+export function routeMessage(message, registry) {
+  const { valid, errors } = validate(message);
+  if (!valid) {
+    return { routed: false, reason: `invalid message: ${errors.join(", ")}` };
+  }
+
+  const { to, from } = message;
+
+  // Broadcast
+  if (to === "*") {
+    const all = registry.listAll();
+    const targets = all
+      .map((a) => a.agentId)
+      .filter((id) => id !== from);
+    if (targets.length === 0) {
+      return { routed: false, reason: "broadcast: no agents registered" };
+    }
+    return { routed: true, targets };
+  }
+
+  // Capability-based routing
+  if (to.startsWith("capability:")) {
+    const capability = to.slice("capability:".length);
+    if (!capability) {
+      return { routed: false, reason: "capability: empty capability name" };
+    }
+    const targets = registry.discover(capability);
+    if (targets.length === 0) {
+      return { routed: false, reason: `capability: no agents with "${capability}"` };
+    }
+    return { routed: true, targets };
+  }
+
+  // Direct addressing
+  const agent = registry.getAgent(to);
+  if (!agent) {
+    return { routed: false, reason: `agent not found: "${to}"` };
+  }
+  return { routed: true, targets: [to] };
+}
+
+/**
+ * Routes a message and collects dead-letter info when delivery fails.
+ *
+ * @param {object} message
+ * @param {object} registry
+ * @returns {{ routed: boolean, targets?: string[], deadLetter?: object }}
+ */
+export function routeOrDeadLetter(message, registry) {
+  const result = routeMessage(message, registry);
+  if (!result.routed) {
+    return {
+      ...result,
+      deadLetter: {
+        originalMessage: message,
+        reason: result.reason,
+        timestamp: new Date().toISOString(),
+      },
+    };
+  }
+  return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "10.0.0",
+  "version": "10.0.2",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {
@@ -21,6 +21,13 @@
   "files": [
     "bin",
     "skills",
+    "hooks",
+    "hud",
+    "scripts",
+    "hub",
+    "mesh",
+    "references",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],

package/references/hosts.json

@@ -0,0 +1,33 @@
+{
+  "hosts": {
+    "ultra4": {
+      "description": "Windows 데스크탑 (22코어/64GB RAM)",
+      "aliases": [
+        "울트라",
+        "울트라4",
+        "데스크탑"
+      ],
+      "default_dir": "~/Desktop/Projects/cli/triflux",
+      "tailscale": {
+        "ip": "100.110.136.64",
+        "dns": "ultra-book-4-1",
+        "ssh_mode": "ssh-over-vpn"
+      },
+      "ssh_user": "SSAFY",
+      "os": "windows",
+      "specs": {
+        "cores": 22,
+        "ram_gb": 64,
+        "codex": "0.118.0",
+        "node": "24.14.0"
+      },
+      "capabilities": ["codex", "claude", "high-memory"]
+    }
+  },
+  "default_host": "ultra4",
+  "triggers": [
+    "원격에서",
+    "다른 머신에서",
+    "다른 컴퓨터에서"
+  ]
+}

package/scripts/__tests__/gen-skill-docs.test.mjs

@@ -0,0 +1,87 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, it } from "node:test";
+
+import { generateSkillDocs } from "../gen-skill-docs.mjs";
+
+function makeTempDir() {
+  return mkdtempSync(join(tmpdir(), "tfx-gen-skill-docs-"));
+}
+
+describe("gen-skill-docs", () => {
+  it("SKILL.md.tmpl 파일을 SKILL.md로 생성한다", () => {
+    const root = makeTempDir();
+    try {
+      const skillsDir = join(root, "skills");
+      const templatesDir = join(skillsDir, "_templates");
+      const skillDir = join(skillsDir, "tfx-sample");
+
+      mkdirSync(templatesDir, { recursive: true });
+      mkdirSync(skillDir, { recursive: true });
+
+      writeFileSync(join(templatesDir, "base.md"), "BASE {{SKILL_NAME}}", "utf8");
+      writeFileSync(join(templatesDir, "deep.md"), "DEEP BLOCK", "utf8");
+
+      writeFileSync(
+        join(skillDir, "SKILL.md.tmpl"),
+        [
+          "---",
+          "name: tfx-sample",
+          "description: sample skill",
+          "---",
+          "{{> base}}",
+          "{{#if DEEP}}",
+          "{{> deep}}",
+          "{{/if}}",
+        ].join("\n"),
+        "utf8",
+      );
+
+      const result = generateSkillDocs({ skillsDir, templatesDir, write: true });
+      assert.equal(result.count, 1);
+
+      const output = readFileSync(join(skillDir, "SKILL.md"), "utf8");
+      assert.match(output, /BASE tfx-sample/);
+      assert.doesNotMatch(output, /DEEP BLOCK/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("deep 스킬은 DEEP 조건부 섹션을 포함한다", () => {
+    const root = makeTempDir();
+    try {
+      const skillsDir = join(root, "skills");
+      const templatesDir = join(skillsDir, "_templates");
+      const skillDir = join(skillsDir, "tfx-deep-sample");
+
+      mkdirSync(templatesDir, { recursive: true });
+      mkdirSync(skillDir, { recursive: true });
+
+      writeFileSync(join(templatesDir, "base.md"), "BASE", "utf8");
+      writeFileSync(join(templatesDir, "deep.md"), "DEEP {{SKILL_NAME}}", "utf8");
+      writeFileSync(
+        join(skillDir, "SKILL.md.tmpl"),
+        [
+          "---",
+          "name: tfx-deep-sample",
+          "description: deep sample",
+          "---",
+          "{{> base}}",
+          "{{#if DEEP}}",
+          "{{> deep}}",
+          "{{/if}}",
+        ].join("\n"),
+        "utf8",
+      );
+
+      generateSkillDocs({ skillsDir, templatesDir, write: true });
+      const output = readFileSync(join(skillDir, "SKILL.md"), "utf8");
+      assert.match(output, /DEEP tfx-deep-sample/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/scripts/__tests__/keyword-detector.test.mjs

@@ -0,0 +1,234 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { compileRules, loadRules, matchRules, resolveConflicts } from "../lib/keyword-rules.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, "..", "..");
+const rulesPath = join(projectRoot, "hooks", "keyword-rules.json");
+const detectorScriptPath = join(projectRoot, "scripts", "keyword-detector.mjs");
+
+// keyword-detector는 import 시 main()이 실행되므로, 테스트 로딩 단계에서만 안전하게 비활성화한다.
+const previousDisable = process.env.TRIFLUX_DISABLE_MAGICWORDS;
+const previousLog = console.log;
+process.env.TRIFLUX_DISABLE_MAGICWORDS = "1";
+console.log = () => {};
+const detectorModule = await import("../keyword-detector.mjs");
+console.log = previousLog;
+if (previousDisable === undefined) {
+  delete process.env.TRIFLUX_DISABLE_MAGICWORDS;
+} else {
+  process.env.TRIFLUX_DISABLE_MAGICWORDS = previousDisable;
+}
+
+const { extractPrompt, sanitizeForKeywordDetection } = detectorModule;
+
+function loadCompiledRules() {
+  const rules = loadRules(rulesPath);
+  assert.equal(rules.length, 33);
+  return compileRules(rules);
+}
+
+function runDetector(prompt) {
+  const payload = { prompt, cwd: projectRoot };
+  const result = spawnSync(process.execPath, [detectorScriptPath], {
+    input: JSON.stringify(payload),
+    encoding: "utf8"
+  });
+
+  assert.equal(result.status, 0, result.stderr);
+  assert.ok(result.stdout.trim(), "keyword-detector 출력이 비어 있습니다.");
+  return JSON.parse(result.stdout.trim());
+}
+
+test("extractPrompt: prompt/message.content/parts[].text 우선순위", () => {
+  assert.equal(
+    extractPrompt({
+      prompt: "from prompt",
+      message: { content: "from message" },
+      parts: [{ text: "from parts" }]
+    }),
+    "from prompt"
+  );
+
+  assert.equal(
+    extractPrompt({
+      prompt: "   ",
+      message: { content: "from message" },
+      parts: [{ text: "from parts" }]
+    }),
+    "from message"
+  );
+
+  assert.equal(
+    extractPrompt({
+      message: { content: [{ text: "from message-part" }] },
+      parts: [{ text: "from parts" }]
+    }),
+    "from message-part"
+  );
+
+  assert.equal(extractPrompt({ parts: [{ text: "from parts" }] }), "from parts");
+});
+
+test("sanitizeForKeywordDetection: 코드블록/URL/파일경로/XML 태그 제거", () => {
+  const input = [
+    "정상 문장",
+    "```sh",
+    "tfx multi",
+    "```",
+    "https://example.com/path?q=1",
+    "C:\\Users\\SSAFY\\Desktop\\Projects\\tools\\triflux",
+    "./hooks/keyword-rules.json",
+    "<tag>jira 이슈 생성</tag>"
+  ].join("\n");
+
+  const sanitized = sanitizeForKeywordDetection(input);
+
+  assert.ok(sanitized.includes("정상 문장"));
+  assert.ok(!sanitized.includes("tfx multi"));
+  assert.ok(!sanitized.includes("https://"));
+  assert.ok(!sanitized.includes("C:\\Users\\"));
+  assert.ok(!sanitized.includes("./hooks/keyword-rules.json"));
+  assert.ok(!sanitized.includes("<tag>"));
+  assert.ok(!sanitized.includes("jira 이슈 생성"));
+});
+
+test("loadRules: 유효한 JSON 로드", () => {
+  const rules = loadRules(rulesPath);
+  assert.equal(rules.length, 33);
+  assert.equal(rules.filter((rule) => rule.skill).length, 20);
+  assert.equal(rules.filter((rule) => rule.mcp_route).length, 10);
+});
+
+test("loadRules: 잘못된 파일 처리", () => {
+  const tempDir = mkdtempSync(join(tmpdir(), "triflux-rules-"));
+  const invalidPath = join(tempDir, "invalid.json");
+  writeFileSync(invalidPath, "{ invalid json", "utf8");
+
+  const malformed = loadRules(invalidPath);
+  const missing = loadRules(join(tempDir, "missing.json"));
+
+  assert.deepEqual(malformed, []);
+  assert.deepEqual(missing, []);
+
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+test("compileRules: 정규식 컴파일 성공", () => {
+  const rules = loadRules(rulesPath);
+  const compiled = compileRules(rules);
+  assert.equal(compiled.length, 33);
+  for (const rule of compiled) {
+    assert.ok(Array.isArray(rule.compiledPatterns));
+    assert.ok(rule.compiledPatterns.length > 0);
+    for (const pattern of rule.compiledPatterns) {
+      assert.ok(pattern instanceof RegExp);
+    }
+  }
+});
+
+test("compileRules: 정규식 컴파일 실패", () => {
+  const compiled = compileRules([
+    {
+      id: "bad-pattern",
+      priority: 1,
+      patterns: [{ source: "[", flags: "" }],
+      skill: "tfx-multi",
+      supersedes: [],
+      exclusive: false,
+      state: null,
+      mcp_route: null
+    }
+  ]);
+
+  assert.deepEqual(compiled, []);
+});
+
+test("matchRules: tfx 키워드 매칭", () => {
+  const compiledRules = loadCompiledRules();
+  const cases = [
+    { text: "tfx multi 세션 시작", expectedId: "tfx-multi" },
+    { text: "tfx auto 돌려줘", expectedId: "tfx-auto" },
+    { text: "tfx codex 로 실행", expectedId: "tfx-codex" },
+    { text: "tfx gemini 로 실행", expectedId: "tfx-gemini" },
+    { text: "canceltfx", expectedId: "tfx-cancel" }
+  ];
+
+  for (const { text, expectedId } of cases) {
+    const clean = sanitizeForKeywordDetection(text);
+    const matches = matchRules(compiledRules, clean);
+    assert.ok(matches.some((match) => match.id === expectedId), `${text} => ${expectedId} 미매칭`);
+  }
+});
+
+test("matchRules: MCP 라우팅 매칭", () => {
+  const compiledRules = loadCompiledRules();
+  const cases = [
+    { text: "노션 페이지 조회해줘", expectedId: "notion-route", expectedRoute: "gemini" },
+    { text: "jira 이슈 생성", expectedId: "jira-route", expectedRoute: "codex" },
+    { text: "크롬 열고 로그인", expectedId: "chrome-route", expectedRoute: "gemini" },
+    { text: "이메일 보내줘", expectedId: "mail-route", expectedRoute: "gemini" },
+    { text: "캘린더 일정 생성", expectedId: "calendar-route", expectedRoute: "gemini" },
+    { text: "playwright 테스트 작성", expectedId: "playwright-route", expectedRoute: "gemini" },
+    { text: "canva 디자인 생성", expectedId: "canva-route", expectedRoute: "gemini" }
+  ];
+
+  for (const { text, expectedId, expectedRoute } of cases) {
+    const matches = matchRules(compiledRules, sanitizeForKeywordDetection(text));
+    const matched = matches.find((match) => match.id === expectedId);
+    assert.ok(matched, `${text} => ${expectedId} 미매칭`);
+    assert.equal(matched.mcp_route, expectedRoute);
+  }
+});
+
+test("matchRules: 일반 대화는 매칭 없음", () => {
+  const compiledRules = loadCompiledRules();
+  const matches = matchRules(compiledRules, sanitizeForKeywordDetection("오늘 점심 메뉴 추천해줘"));
+  assert.deepEqual(matches, []);
+});
+
+test("resolveConflicts: priority 정렬 및 supersedes 처리", () => {
+  const resolved = resolveConflicts([
+    { id: "rule-c", priority: 3, supersedes: [], exclusive: false },
+    { id: "rule-b", priority: 2, supersedes: ["rule-c"], exclusive: false },
+    { id: "rule-a", priority: 1, supersedes: [], exclusive: false },
+    { id: "rule-a", priority: 1, supersedes: [], exclusive: false }
+  ]);
+
+  assert.deepEqual(
+    resolved.map((rule) => rule.id),
+    ["rule-a", "rule-b"]
+  );
+});
+
+test("resolveConflicts: exclusive 처리", () => {
+  const resolved = resolveConflicts([
+    { id: "normal", priority: 1, supersedes: [], exclusive: false },
+    { id: "exclusive", priority: 0, supersedes: [], exclusive: true },
+    { id: "later", priority: 2, supersedes: [], exclusive: false }
+  ]);
+
+  assert.deepEqual(resolved.map((rule) => rule.id), ["exclusive"]);
+});
+
+test("코드블록 내 키워드: sanitize 후 매칭 안 됨", () => {
+  const compiledRules = loadCompiledRules();
+  const input = ["```txt", "tfx multi", "jira 이슈 생성", "```"].join("\n");
+  const clean = sanitizeForKeywordDetection(input);
+  const matches = matchRules(compiledRules, clean);
+  assert.deepEqual(matches, []);
+});
+
+test("OMC 키워드와 triflux 키워드 비간섭 + TRIFLUX 네임스페이스", () => {
+  const omcLike = runDetector("my tfx multi 세션 보여줘");
+  assert.equal(omcLike.suppressOutput, true);
+
+  const triflux = runDetector("tfx multi 세션 시작");
+  const additionalContext = triflux?.hookSpecificOutput?.additionalContext || "";
+  assert.match(additionalContext, /^\[TRIFLUX MAGIC KEYWORD: tfx-multi\]/);
+});