triflux 10.0.0 → 10.0.2

package/scripts/__tests__/mcp-guard-engine.test.mjs

@@ -0,0 +1,118 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { describe, it, afterEach } from "node:test";
+import { fileURLToPath } from "node:url";
+
+import {
+  isWatchedPath,
+  loadRegistry,
+  remediate,
+  resolveHubUrl,
+  scanForStdioServers,
+} from "../lib/mcp-guard-engine.mjs";
+
+const TEST_DIR = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(TEST_DIR, "..", "..");
+const originalHome = {
+  HOME: process.env.HOME,
+  USERPROFILE: process.env.USERPROFILE,
+  TFX_HUB_PORT: process.env.TFX_HUB_PORT,
+};
+
+function createHomeDir(prefix = "mcp-guard-") {
+  const base = join(tmpdir(), `${prefix}${Date.now()}-${Math.random().toString(16).slice(2)}`);
+  mkdirSync(base, { recursive: true });
+  mkdirSync(join(base, ".gemini"), { recursive: true });
+  mkdirSync(join(base, ".claude", "cache", "tfx-hub"), { recursive: true });
+  mkdirSync(join(base, ".codex"), { recursive: true });
+  return base;
+}
+
+function withHome(homeDir) {
+  process.env.HOME = homeDir;
+  process.env.USERPROFILE = homeDir;
+}
+
+afterEach(() => {
+  if (originalHome.HOME === undefined) delete process.env.HOME;
+  else process.env.HOME = originalHome.HOME;
+
+  if (originalHome.USERPROFILE === undefined) delete process.env.USERPROFILE;
+  else process.env.USERPROFILE = originalHome.USERPROFILE;
+
+  if (originalHome.TFX_HUB_PORT === undefined) delete process.env.TFX_HUB_PORT;
+  else process.env.TFX_HUB_PORT = originalHome.TFX_HUB_PORT;
+});
+
+describe("mcp guard engine", () => {
+  it("loads the MCP registry", () => {
+    const registry = loadRegistry();
+    assert.equal(registry.version, 1);
+    assert.equal(registry.servers["tfx-hub"].url, "http://127.0.0.1:27888/mcp");
+    assert.equal(registry.policies.watched_paths.length, 5);
+  });
+
+  it("matches watched paths for Gemini and local .mcp.json", () => {
+    const homeDir = createHomeDir();
+    withHome(homeDir);
+
+    assert.equal(isWatchedPath(join(homeDir, ".gemini", "settings.json")), true);
+    assert.equal(isWatchedPath(join(PROJECT_ROOT, "nested", ".mcp.json")), true);
+    assert.equal(isWatchedPath(join(PROJECT_ROOT, "nested", "settings.yaml")), false);
+  });
+
+  it("detects stdio MCP servers from JSON config", () => {
+    const homeDir = createHomeDir();
+    withHome(homeDir);
+
+    const settingsPath = join(homeDir, ".gemini", "settings.json");
+    writeFileSync(settingsPath, JSON.stringify({
+      mcpServers: {
+        "unsafe-stdio": { command: "node", args: ["server.js"] },
+        "safe-url": { url: "http://127.0.0.1:27888/mcp" },
+      },
+    }, null, 2));
+
+    const found = scanForStdioServers(settingsPath);
+    assert.deepEqual(found.map((server) => server.name), ["unsafe-stdio"]);
+  });
+
+  it("replaces stdio MCP entries with tfx-hub and writes a backup", () => {
+    const homeDir = createHomeDir();
+    withHome(homeDir);
+
+    const pidPath = join(homeDir, ".claude", "cache", "tfx-hub", "hub.pid");
+    writeFileSync(pidPath, JSON.stringify({ host: "127.0.0.1", port: 30123 }), "utf8");
+
+    const settingsPath = join(homeDir, ".gemini", "settings.json");
+    writeFileSync(settingsPath, JSON.stringify({
+      mcpServers: {
+        "unsafe-stdio": { command: "node", args: ["server.js"] },
+      },
+    }, null, 2));
+
+    const result = remediate(settingsPath, scanForStdioServers(settingsPath), { stdio_action: "replace-with-hub" });
+    const updated = JSON.parse(readFileSync(settingsPath, "utf8"));
+
+    assert.equal(result.modified, true);
+    assert.equal(existsSync(`${settingsPath}.bak`), true);
+    assert.deepEqual(result.removedServers, ["unsafe-stdio"]);
+    assert.equal(updated.mcpServers["tfx-hub"].url, "http://127.0.0.1:30123/mcp");
+    assert.equal(Object.hasOwn(updated.mcpServers, "unsafe-stdio"), false);
+  });
+
+  it("uses hub.pid port before registry fallback when resolving Hub URL", () => {
+    const homeDir = createHomeDir();
+    withHome(homeDir);
+
+    writeFileSync(
+      join(homeDir, ".claude", "cache", "tfx-hub", "hub.pid"),
+      JSON.stringify({ host: "127.0.0.1", port: 29991 }),
+      "utf8",
+    );
+
+    assert.equal(resolveHubUrl(), "http://127.0.0.1:29991/mcp");
+  });
+});

package/scripts/__tests__/remote-spawn-transfer.test.mjs

@@ -0,0 +1,117 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  buildRemoteTransferPlan,
+  extractExplicitFileTokens,
+} from "../lib/remote-spawn-transfer.mjs";
+
+function makeTempDir() {
+  return mkdtempSync(join(tmpdir(), "tfx-remote-spawn-transfer-"));
+}
+
+describe("remote-spawn transfer plan", () => {
+  it("extractExplicitFileTokens는 명시적 파일 토큰만 추출한다", () => {
+    const source = [
+      "Read [PRD](.omx/plans/prd.md) and `docs/spec.md`.",
+      "Also open \"./notes.txt\" and 'http://example.com'.",
+    ].join("\n");
+
+    const tokens = extractExplicitFileTokens(source);
+
+    assert.deepEqual(tokens.sort(), ["./notes.txt", ".omx/plans/prd.md", "docs/spec.md"].sort());
+  });
+
+  it("handoff + 참조 파일 전송 계획과 프롬프트 재작성", () => {
+    const root = makeTempDir();
+    try {
+      mkdirSync(join(root, "docs"), { recursive: true });
+      writeFileSync(join(root, "prd.md"), "prd body", "utf8");
+      writeFileSync(join(root, "docs", "spec.md"), "spec body", "utf8");
+      writeFileSync(
+        join(root, "handoff.md"),
+        [
+          "Open \"./prd.md\" before anything else.",
+          "Then inspect `docs/spec.md` and [again](docs/spec.md).",
+        ].join("\n"),
+        "utf8",
+      );
+
+      const plan = buildRemoteTransferPlan({
+        cwd: root,
+        handoffPath: "handoff.md",
+        maxBytes: 1024 * 1024,
+        remoteStageRoot: "/remote/stage/abc123",
+        userPrompt: "continue with execution",
+      });
+
+      assert.equal(plan.transfers.length, 3);
+      assert.equal(plan.transfers[0].type, "handoff");
+      assert.equal(plan.transfers[1].type, "reference");
+      assert.equal(plan.transfers[2].type, "reference");
+
+      assert.match(plan.prompt, /Staged handoff file: \/remote\/stage\/abc123\/handoff\/handoff\.md/);
+      assert.match(plan.prompt, /\/remote\/stage\/abc123\/refs\/\d{2}-prd\.md/);
+      assert.match(plan.prompt, /\/remote\/stage\/abc123\/refs\/\d{2}-spec\.md/);
+      assert.equal(plan.prompt.includes("./prd.md"), false);
+      assert.equal(plan.prompt.includes("docs/spec.md"), false);
+      assert.match(plan.prompt, /---\n\ncontinue with execution$/);
+    } finally {
+      rmSync(root, { force: true, recursive: true });
+    }
+  });
+
+  it("누락된 참조 파일은 SSH 전 로컬에서 실패한다", () => {
+    const root = makeTempDir();
+    try {
+      writeFileSync(join(root, "handoff.md"), "Read `./missing.md`", "utf8");
+      assert.throws(
+        () => buildRemoteTransferPlan({
+          cwd: root,
+          handoffPath: "handoff.md",
+          maxBytes: 1024 * 1024,
+          remoteStageRoot: "/remote/stage/abc123",
+        }),
+        /referenced file not found:/,
+      );
+    } finally {
+      rmSync(root, { force: true, recursive: true });
+    }
+  });
+
+  it("MAX_HANDOFF_BYTES 제한을 handoff와 참조 파일 모두에 적용한다", () => {
+    const root = makeTempDir();
+    try {
+      writeFileSync(join(root, "big-ref.txt"), "x".repeat(32), "utf8");
+      writeFileSync(join(root, "handoff.md"), "Open ./big-ref.txt", "utf8");
+
+      assert.throws(
+        () => buildRemoteTransferPlan({
+          cwd: root,
+          handoffPath: "handoff.md",
+          maxBytes: 16,
+          remoteStageRoot: "/remote/stage/abc123",
+        }),
+        /referenced file too large:/,
+      );
+    } finally {
+      rmSync(root, { force: true, recursive: true });
+    }
+  });
+
+  it("handoff가 없으면 기존 prompt 전달 동작을 유지한다", () => {
+    const plan = buildRemoteTransferPlan({
+      handoffPath: null,
+      maxBytes: 1024,
+      remoteStageRoot: "/remote/stage/abc123",
+      userPrompt: "only prompt",
+    });
+
+    assert.equal(plan.prompt, "only prompt");
+    assert.deepEqual(plan.transfers, []);
+    assert.equal(plan.stagedHandoffPath, null);
+  });
+});

package/scripts/__tests__/remote-spawn.test.mjs

@@ -0,0 +1,92 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { __remoteSpawnTest } from "../remote-spawn.mjs";
+
+const { startSpawnExitWatcher, watchSpawnSessionExit } = __remoteSpawnTest;
+
+describe("remote-spawn watcher", () => {
+  it("lead pane dead 상태가 grace 기간 유지되면 세션을 정리한다", async () => {
+    let nowMs = 0;
+    let pollIndex = 0;
+    const killed = [];
+    const statuses = [
+      { isDead: false, exitCode: null },
+      { isDead: true, exitCode: 0 },
+      { isDead: true, exitCode: 0 },
+      { isDead: true, exitCode: 0 },
+    ];
+
+    const result = await watchSpawnSessionExit("tfx-spawn-unit", {
+      pollMs: 100,
+      graceMs: 200,
+      maxWaitMs: 1000,
+      sessionExists: () => true,
+      getPaneStatus: () => statuses[Math.min(pollIndex++, statuses.length - 1)],
+      killSession: (name) => killed.push(name),
+      now: () => nowMs,
+      sleep: async (ms) => { nowMs += ms; },
+    });
+
+    assert.equal(result.cleaned, true);
+    assert.equal(result.reason, "pane-dead");
+    assert.deepEqual(killed, ["tfx-spawn-unit"]);
+  });
+
+  it("live session은 정리하지 않고 timeout으로 종료한다", async () => {
+    let nowMs = 0;
+    let killCount = 0;
+
+    const result = await watchSpawnSessionExit("tfx-spawn-timeout", {
+      pollMs: 100,
+      graceMs: 200,
+      maxWaitMs: 250,
+      sessionExists: () => true,
+      getPaneStatus: () => ({ isDead: false, exitCode: null }),
+      killSession: () => { killCount += 1; },
+      now: () => nowMs,
+      sleep: async (ms) => { nowMs += ms; },
+    });
+
+    assert.equal(result.cleaned, false);
+    assert.equal(result.reason, "timeout");
+    assert.equal(killCount, 0);
+  });
+
+  it("detached watcher를 현재 cleanup watcher 인자로 실행한다", () => {
+    const calls = [];
+    const started = startSpawnExitWatcher("tfx-spawn-detached", {
+      force: true,
+      execPath: "node-test",
+      scriptPath: "C:/tmp/remote-spawn.mjs",
+      spawnFn: (file, args, options) => {
+        calls.push({ file, args, options, unrefCalled: false });
+        return {
+          unref() {
+            calls[0].unrefCalled = true;
+          },
+        };
+      },
+    });
+
+    assert.equal(started, true);
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].file, "node-test");
+    assert.deepEqual(calls[0].args, [
+      "C:/tmp/remote-spawn.mjs",
+      "--watch-cleanup",
+      "tfx-spawn-detached",
+      "--pane",
+      "tfx-spawn-detached:0.0",
+      "--poll-ms",
+      "1000",
+      "--grace-ms",
+      "1500",
+      "--max-ms",
+      "3600000",
+    ]);
+    assert.equal(calls[0].options.detached, true);
+    assert.equal(calls[0].options.stdio, "ignore");
+    assert.equal(calls[0].unrefCalled, true);
+  });
+});

package/scripts/__tests__/skill-template.test.mjs

@@ -0,0 +1,193 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, it } from "node:test";
+
+import {
+  buildSkillTemplateContext,
+  loadTemplatePartials,
+  parseFrontmatter,
+  renderSkillTemplate,
+} from "../lib/skill-template.mjs";
+import { generateSkillDocs } from "../gen-skill-docs.mjs";
+
+function makeTempDir() {
+  return mkdtempSync(join(tmpdir(), "tfx-skill-template-"));
+}
+
+describe("skill-template engine", () => {
+  it("변수 치환 + include + 조건부 블록을 렌더링한다", () => {
+    const template = [
+      "{{> base}}",
+      "",
+      "{{#if DEEP}}",
+      "{{> deep}}",
+      "{{/if}}",
+      "",
+      "name={{SKILL_NAME}}",
+    ].join("\n");
+
+    const output = renderSkillTemplate(template, {
+      SKILL_NAME: "tfx-deep-plan",
+      SKILL_DESCRIPTION: "consensus planner",
+      DEEP: true,
+    }, {
+      partials: {
+        base: "desc={{SKILL_DESCRIPTION}}",
+        deep: "deep-enabled",
+      },
+    });
+
+    assert.match(output, /desc=consensus planner/);
+    assert.match(output, /deep-enabled/);
+    assert.match(output, /name=tfx-deep-plan/);
+  });
+
+  it("조건부가 false면 블록을 제거한다", () => {
+    const template = "start\n{{#if DEEP}}hidden{{/if}}\nend";
+    const output = renderSkillTemplate(template, { DEEP: false }, { partials: {} });
+    assert.equal(output, "start\n\nend");
+  });
+
+  it("누락된 partial 또는 변수는 에러를 던진다", () => {
+    assert.throws(
+      () => renderSkillTemplate("{{> missing}}", {}, { partials: {} }),
+      /Missing partial: missing/,
+    );
+
+    assert.throws(
+      () => renderSkillTemplate("{{SKILL_NAME}}", {}, { partials: {} }),
+      /Missing template variable: SKILL_NAME/,
+    );
+  });
+
+  it("frontmatter와 context 기본값을 파싱한다", () => {
+    const source = [
+      "---",
+      "name: tfx-auto",
+      "description: >",
+      "  auto orchestrator",
+      "deep: true",
+      "---",
+      "{{SKILL_NAME}} / {{SKILL_DESCRIPTION}} / {{DEEP}}",
+    ].join("\n");
+
+    const parsed = parseFrontmatter(source);
+    assert.equal(parsed.data.name, "tfx-auto");
+    assert.equal(parsed.data.description, "auto orchestrator");
+
+    const context = buildSkillTemplateContext({
+      frontmatter: parsed.data,
+      skillDirName: "fallback-name",
+    });
+
+    assert.equal(context.SKILL_NAME, "tfx-auto");
+    assert.equal(context.SKILL_DESCRIPTION, "auto orchestrator");
+    assert.equal(context.DEEP, true);
+  });
+
+  it("partial 디렉토리에서 이름/경로 alias를 함께 로드한다", () => {
+    const root = makeTempDir();
+    try {
+      mkdirSync(join(root, "nested"), { recursive: true });
+      writeFileSync(join(root, "base.md"), "base-partial", "utf8");
+      writeFileSync(join(root, "nested", "telemetry.md"), "telemetry-partial", "utf8");
+
+      const partials = loadTemplatePartials(root);
+      assert.equal(partials.base, "base-partial");
+      assert.equal(partials["nested/telemetry"], "telemetry-partial");
+      assert.equal(partials.telemetry, "telemetry-partial");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("순환 partial include를 감지한다", () => {
+    assert.throws(
+      () =>
+        renderSkillTemplate("{{> A}}", {}, {
+          partials: {
+            A: "A -> {{> B}}",
+            B: "B -> {{> A}}",
+          },
+        }),
+      /Circular partial include: A -> B -> A/,
+    );
+  });
+
+  it("빈 frontmatter 블록도 정상 파싱한다", () => {
+    const parsed = parseFrontmatter(["---", "---", "body"].join("\n"));
+    assert.deepEqual(parsed.data, {});
+    assert.equal(parsed.body, "body");
+  });
+
+  it("중복 frontmatter 키는 마지막 값을 우선한다", () => {
+    const parsed = parseFrontmatter([
+      "---",
+      "name: first",
+      "name: second",
+      "---",
+      "x",
+    ].join("\n"));
+    assert.equal(parsed.data.name, "second");
+  });
+
+  it("특수문자 변수 키(점/하이픈)를 치환한다", () => {
+    const output = renderSkillTemplate("{{FOO.BAR}}/{{FOO-BAR}}", {
+      "FOO.BAR": "dot",
+      "FOO-BAR": "dash",
+    }, { partials: {} });
+    assert.equal(output, "dot/dash");
+  });
+
+  it("중첩 조건 블록을 안쪽 조건값에 따라 렌더링한다", () => {
+    const template = "{{#if A}}open-{{#if B}}inner{{/if}}-close{{/if}}";
+    assert.equal(renderSkillTemplate(template, { A: true, B: true }, { partials: {} }), "open-inner-close");
+    assert.equal(renderSkillTemplate(template, { A: true, B: false }, { partials: {} }), "open--close");
+    assert.equal(renderSkillTemplate(template, { A: false, B: true }, { partials: {} }), "");
+  });
+
+  it("1000줄 이상 대형 템플릿도 렌더링한다", () => {
+    const lines = Array.from({ length: 1_200 }, (_v, i) => `line-${i}`);
+    const template = `${lines.join("\n")}\nname={{SKILL_NAME}}`;
+    const output = renderSkillTemplate(template, { SKILL_NAME: "big-template" }, { partials: {} });
+
+    const renderedLines = output.split("\n");
+    assert.equal(renderedLines.length, 1_201);
+    assert.equal(renderedLines[0], "line-0");
+    assert.equal(renderedLines.at(-1), "name=big-template");
+  });
+
+  it("gen-skill-docs에서 누락 partial 참조 시 에러를 전파한다", () => {
+    const root = makeTempDir();
+    try {
+      const skillsDir = join(root, "skills");
+      const templatesDir = join(skillsDir, "_templates");
+      const skillDir = join(skillsDir, "tfx-missing-partial");
+
+      mkdirSync(templatesDir, { recursive: true });
+      mkdirSync(skillDir, { recursive: true });
+
+      writeFileSync(join(templatesDir, "base.md"), "base={{SKILL_NAME}}", "utf8");
+      writeFileSync(
+        join(skillDir, "SKILL.md.tmpl"),
+        [
+          "---",
+          "name: tfx-missing-partial",
+          "---",
+          "{{> base}}",
+          "{{> missing_partial}}",
+        ].join("\n"),
+        "utf8",
+      );
+
+      assert.throws(
+        () => generateSkillDocs({ skillsDir, templatesDir, write: false }),
+        /Missing partial: missing_partial/,
+      );
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/scripts/__tests__/smoke.test.mjs

@@ -0,0 +1,34 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+describe("smoke: 주요 모듈 import 검증", () => {
+  it("scripts/lib/keyword-rules.mjs — 순수 함수 export", async () => {
+    const mod = await import("../lib/keyword-rules.mjs");
+    assert.equal(typeof mod.loadRules, "function");
+    assert.equal(typeof mod.compileRules, "function");
+    assert.equal(typeof mod.matchRules, "function");
+    assert.equal(typeof mod.resolveConflicts, "function");
+  });
+
+  it("hub/team/shared.mjs — ANSI 상수 export", async () => {
+    const mod = await import("../../hub/team/shared.mjs");
+    assert.equal(typeof mod.AMBER, "string");
+    assert.equal(typeof mod.RESET, "string");
+  });
+
+  it("hub/team/staleState.mjs — stale 상태 유틸 export", async () => {
+    const mod = await import("../../hub/team/staleState.mjs");
+    assert.equal(typeof mod.TEAM_STATE_FILE_NAME, "string");
+    assert.equal(typeof mod.STALE_TEAM_MAX_AGE_MS, "number");
+  });
+
+  it("hub/pipeline/transitions.mjs — 파이프라인 전이 규칙 export", async () => {
+    const mod = await import("../../hub/pipeline/transitions.mjs");
+    assert.ok(Array.isArray(mod.PHASES));
+    assert.ok(mod.PHASES.includes("plan"));
+    assert.ok(mod.PHASES.includes("complete"));
+    assert.ok(mod.TERMINAL instanceof Set);
+    assert.ok(mod.TERMINAL.has("complete"));
+    assert.ok(mod.TERMINAL.has("failed"));
+  });
+});

package/scripts/cache-buildup.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// scripts/cache-buildup.mjs — legacy wrapper for cache-warmup
+
+import { fileURLToPath } from "node:url";
+import {
+  buildAll,
+  checkSearchEngines,
+  extractProjectMeta,
+  formatBuildSummary,
+  probeTierEnvironment,
+  scanCodexSkills,
+} from "./cache-warmup.mjs";
+
+export {
+  buildAll,
+  checkSearchEngines,
+  extractProjectMeta,
+  probeTierEnvironment,
+  scanCodexSkills,
+};
+
+async function main() {
+  const summary = buildAll({ force: process.argv.includes("--force") });
+  console.log(formatBuildSummary(summary, { label: "cache-buildup" }));
+  if (!summary.ok) process.exitCode = 1;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  await main();
+}