@triflux/core 10.1.0 → 10.25.1

package/scripts/lib/psmux-info.mjs

@@ -8,10 +8,9 @@ export const PSMUX_REQUIRED_COMMANDS = [
   "capture-pane",
 ];
 
-export const PSMUX_OPTIONAL_COMMANDS = [
-  "detach-client",
-];
+export const PSMUX_OPTIONAL_COMMANDS = ["detach-client"];
 
+// Windows 패키지 매니저 — winget/scoop/choco 는 Windows 전용
 export const PSMUX_INSTALL_COMMANDS = [
   "winget install marlocarlo.psmux",
   "scoop install psmux",
@@ -26,16 +25,73 @@ export const PSMUX_UPDATE_COMMANDS = [
   "cargo install psmux --force",
 ];
 
-export function formatPsmuxCommandList(commands = PSMUX_INSTALL_COMMANDS, indent = "") {
+// macOS 전용 — brew 가 표준, cargo 는 cross-platform fallback
+export const PSMUX_INSTALL_COMMANDS_DARWIN = [
+  "brew install psmux",
+  "cargo install psmux",
+];
+
+export const PSMUX_UPDATE_COMMANDS_DARWIN = [
+  "brew upgrade psmux",
+  "cargo install psmux --force",
+];
+
+// Linux 전용 — cargo 만 cross-platform 지원, distro 패키지는 미제공
+export const PSMUX_INSTALL_COMMANDS_LINUX = ["cargo install psmux"];
+
+export const PSMUX_UPDATE_COMMANDS_LINUX = ["cargo install psmux --force"];
+
+// PR #258 OS-primary 분기 정책: macOS/Linux 는 tmux 가 POSIX 표준 primary,
+// psmux 는 선택형. native teams fallback (tmux 또는 child process spawn) 으로 동작 가능.
+export const PSMUX_FALLBACK_NOTE_DARWIN =
+  "macOS 에서는 tmux 가 표준 멀티플렉서이며, " +
+  "triflux 는 psmux 없이도 native teams fallback 으로 멀티모델 병렬 실행을 지원합니다.";
+
+export const PSMUX_FALLBACK_NOTE_LINUX =
+  "Linux 에서는 tmux 가 표준 멀티플렉서이며, " +
+  "triflux 는 psmux 없이도 native teams fallback 으로 멀티모델 병렬 실행을 지원합니다.";
+
+export function getPsmuxInstallCommandsFor(platform = process.platform) {
+  if (platform === "darwin") return PSMUX_INSTALL_COMMANDS_DARWIN;
+  if (platform === "linux") return PSMUX_INSTALL_COMMANDS_LINUX;
+  // win32 또는 기타 (BSD 등) → Windows 풀 리스트로 폴백 (변경 전 동작 유지)
+  return PSMUX_INSTALL_COMMANDS;
+}
+
+export function getPsmuxUpdateCommandsFor(platform = process.platform) {
+  if (platform === "darwin") return PSMUX_UPDATE_COMMANDS_DARWIN;
+  if (platform === "linux") return PSMUX_UPDATE_COMMANDS_LINUX;
+  return PSMUX_UPDATE_COMMANDS;
+}
+
+export function getPsmuxFallbackNoteFor(platform = process.platform) {
+  if (platform === "darwin") return PSMUX_FALLBACK_NOTE_DARWIN;
+  if (platform === "linux") return PSMUX_FALLBACK_NOTE_LINUX;
+  return null;
+}
+
+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 formatPsmuxInstallGuidance(
+  indent = "",
+  platform = process.platform,
+) {
+  const commands = getPsmuxInstallCommandsFor(platform);
+  const list = formatPsmuxCommandList(commands, indent);
+  const note = getPsmuxFallbackNoteFor(platform);
+  return note ? `${list}\n${indent}(${note})` : list;
 }
 
-export function formatPsmuxUpdateGuidance(indent = "") {
-  return formatPsmuxCommandList(PSMUX_UPDATE_COMMANDS, indent);
+export function formatPsmuxUpdateGuidance(
+  indent = "",
+  platform = process.platform,
+) {
+  return formatPsmuxCommandList(getPsmuxUpdateCommandsFor(platform), indent);
 }
 
 export function parsePsmuxVersion(output = "") {
@@ -44,8 +100,12 @@ export function parsePsmuxVersion(output = "") {
 }
 
 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);
+  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;

package/scripts/lib/quota.mjs

@@ -0,0 +1,47 @@
+export const QUOTA_PATTERNS = [
+  /usage limit exceeded/i,
+  /rate limit exceeded/i,
+  /rate limit reached/i,
+  /try again at/i,
+  /purchase more credits/i,
+  /quota exceeded/i,
+  /RESOURCE_EXHAUSTED/i,
+  /rateLimitExceeded/i,
+  /Too Many Requests/i,
+  /rate_limit_error/i,
+  /overloaded_error/i,
+  /insufficient_quota/i,
+];
+
+export class QuotaStreamBuffer {
+  constructor({ maxBytes = 65536 } = {}) {
+    this.maxBytes = maxBytes;
+    this.text = "";
+  }
+
+  push(chunk) {
+    this.text += Buffer.isBuffer(chunk)
+      ? chunk.toString("utf8")
+      : String(chunk);
+    if (this.text.length > this.maxBytes) {
+      this.text = this.text.slice(-this.maxBytes);
+    }
+    return detectQuotaText(this.text);
+  }
+}
+
+export function detectQuotaText(text = "") {
+  return QUOTA_PATTERNS.some((pattern) => pattern.test(text));
+}
+
+export function getRerouteTarget(cliType) {
+  switch (cliType) {
+    case "codex":
+    case "gemini":
+      return "antigravity";
+    case "antigravity":
+      return "codex";
+    default:
+      return null;
+  }
+}

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

@@ -13,22 +13,37 @@ function normalizeMarkdownTarget(raw) {
 function sanitizeToken(raw) {
   let token = String(raw || "").trim();
   if (!token) return "";
-  token = token.replace(/^[<(]+/u, "").replace(/[)>.,;:!?]+$/u, "").trim();
+  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.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 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;
+  return (
+    hasPathSeparator ||
+    hasDotPrefix ||
+    isHomeRelative ||
+    isWindowsAbs ||
+    hasFileLikeSuffix
+  );
 }
 
 export function extractExplicitFileTokens(text) {
@@ -67,7 +82,9 @@ function validateTransferFile(filePath, maxBytes) {
     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}`);
+    throw new Error(
+      `referenced file too large: ${stats.size} bytes (max ${maxBytes}) for ${filePath}`,
+    );
   }
   return stats.size;
 }
@@ -132,16 +149,23 @@ export function buildRemoteTransferPlan(options = {}) {
   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 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})`);
+    throw new Error(
+      `too many referenced files: ${tokens.length} (max ${maxReferenceFiles})`,
+    );
   }
 
   const stagedByLocalPath = new Map();
@@ -166,7 +190,10 @@ export function buildRemoteTransferPlan(options = {}) {
       });
     }
 
-    replacements.push({ token, stagedPath: stagedByLocalPath.get(resolvedPath) });
+    replacements.push({
+      token,
+      stagedPath: stagedByLocalPath.get(resolvedPath),
+    });
   }
 
   const replacementEntries = Array.from(
@@ -189,7 +216,10 @@ export function buildRemoteTransferPlan(options = {}) {
 
   return {
     prompt,
-    replacements: replacementEntries.map(([token, stagedPath]) => ({ stagedPath, token })),
+    replacements: replacementEntries.map(([token, stagedPath]) => ({
+      stagedPath,
+      token,
+    })),
     stagedHandoffPath,
     transfers,
   };

package/scripts/lib/skill-state.mjs

@@ -0,0 +1,220 @@
+import {
+  access,
+  mkdir,
+  open,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { basename, join } from "node:path";
+
+const DEFAULT_STATE_DIR = join(process.cwd(), ".tfx", "state");
+const STOP_HOOKS = new Map();
+
+function stateFilePath(stateDir, skillName) {
+  return join(stateDir, `${skillName}-active.json`);
+}
+
+function assertValidSkillName(skillName) {
+  if (basename(skillName) !== skillName) {
+    throw new Error(`Invalid skill name: ${skillName}`);
+  }
+}
+
+function assertValidOnStop(onStop) {
+  if (onStop !== undefined && typeof onStop !== "function") {
+    throw new TypeError("onStop must be a function");
+  }
+}
+
+async function readStateFile(filePath) {
+  try {
+    const raw = await readFile(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function rememberStopHook(filePath, onStop) {
+  if (typeof onStop === "function") {
+    STOP_HOOKS.set(filePath, onStop);
+    return;
+  }
+  STOP_HOOKS.delete(filePath);
+}
+
+function logStopHookWarning(message, error) {
+  if (error) {
+    console.warn(message, error);
+    return;
+  }
+  console.warn(message);
+}
+
+async function runStopHook(filePath, state, onStop) {
+  if (!state?.hasStopHook) {
+    STOP_HOOKS.delete(filePath);
+    return;
+  }
+
+  const hook = onStop ?? STOP_HOOKS.get(filePath);
+  STOP_HOOKS.delete(filePath);
+
+  if (typeof hook !== "function") {
+    return;
+  }
+
+  try {
+    await hook({
+      skillName: state.skillName,
+      filePath,
+      state,
+    });
+  } catch (error) {
+    logStopHookWarning(
+      `Failed to run stop-hook for skill: ${state.skillName}`,
+      error,
+    );
+  }
+}
+
+/**
+ * Activate a skill by writing its state file.
+ * Throws if the skill is already active.
+ *
+ * @param {string} skillName
+ * @param {{ stateDir?: string, onStop?: (() => Promise<void> | void) }} options
+ */
+export async function activateSkill(
+  skillName,
+  { stateDir = DEFAULT_STATE_DIR, onStop } = {},
+) {
+  assertValidSkillName(skillName);
+  assertValidOnStop(onStop);
+
+  await mkdir(stateDir, { recursive: true });
+
+  const filePath = stateFilePath(stateDir, skillName);
+  const lockPath = `${filePath}.lock`;
+  const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  let lockHandle;
+
+  try {
+    lockHandle = await open(lockPath, "wx");
+    try {
+      await access(filePath);
+      throw new Error(`Skill already active: ${skillName}`);
+    } catch (error) {
+      if (error?.message === `Skill already active: ${skillName}`) {
+        throw error;
+      }
+      if (error?.code !== "ENOENT") {
+        throw error;
+      }
+    }
+
+    const state = {
+      skillName,
+      pid: process.pid,
+      activatedAt: Date.now(),
+      hasStopHook: typeof onStop === "function",
+    };
+    await writeFile(tmpPath, JSON.stringify(state), "utf8");
+    await rename(tmpPath, filePath);
+    rememberStopHook(filePath, onStop);
+  } finally {
+    await rm(tmpPath, { force: true }).catch(() => {});
+    if (lockHandle) {
+      await lockHandle.close().catch(() => {});
+    }
+    await rm(lockPath, { force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Deactivate a skill by removing its state file.
+ * Does not throw if the file does not exist.
+ *
+ * @param {string} skillName
+ * @param {{ stateDir?: string, onStop?: (() => Promise<void> | void) }} options
+ */
+export async function deactivateSkill(
+  skillName,
+  { stateDir = DEFAULT_STATE_DIR, onStop } = {},
+) {
+  assertValidOnStop(onStop);
+
+  const filePath = stateFilePath(stateDir, skillName);
+  const state = await readStateFile(filePath);
+
+  try {
+    await runStopHook(filePath, state, onStop);
+  } finally {
+    STOP_HOOKS.delete(filePath);
+    await rm(filePath, { force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Return all currently active skills by scanning *-active.json files.
+ *
+ * @param {{ stateDir?: string }} options
+ * @returns {Promise<Array<{ skillName: string, pid: number, activatedAt: number, hasStopHook?: boolean }>>}
+ */
+export async function getActiveSkills({ stateDir = DEFAULT_STATE_DIR } = {}) {
+  let entries;
+  try {
+    entries = await readdir(stateDir);
+  } catch {
+    return [];
+  }
+
+  const results = [];
+  for (const entry of entries) {
+    if (!entry.endsWith("-active.json")) continue;
+    const state = await readStateFile(join(stateDir, entry));
+    if (state) {
+      results.push(state);
+    }
+  }
+  return results;
+}
+
+/**
+ * Remove state files for skills whose processes are no longer alive.
+ *
+ * @param {{ stateDir?: string }} options
+ * @returns {Promise<string[]>} list of pruned skill names
+ */
+export async function pruneOrphanSkillStates({
+  stateDir = DEFAULT_STATE_DIR,
+} = {}) {
+  const active = await getActiveSkills({ stateDir });
+  const pruned = [];
+
+  for (const state of active) {
+    let alive = true;
+    try {
+      process.kill(state.pid, 0);
+    } catch {
+      alive = false;
+    }
+
+    if (!alive) {
+      const filePath = stateFilePath(stateDir, state.skillName);
+      STOP_HOOKS.delete(filePath);
+      if (state.hasStopHook) {
+        logStopHookWarning(
+          `Skipping stop-hook for orphaned skill state: ${state.skillName}`,
+        );
+      }
+      await rm(filePath, { force: true }).catch(() => {});
+      pruned.push(state.skillName);
+    }
+  }
+
+  return pruned;
+}

package/scripts/lib/skill-template.mjs

@@ -1,5 +1,12 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, extname, isAbsolute, join, relative, resolve } from "node:path";
+import {
+  basename,
+  extname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+} from "node:path";
 
 const IF_TAG_RE = /{{\s*(#if\s+([A-Za-z0-9_.-]+)|\/if)\s*}}/g;
 const PARTIAL_RE = /{{>\s*([A-Za-z0-9_./-]+)\s*}}/g;
@@ -187,7 +194,8 @@ function resolveIncludeContent(includeName, options) {
   const fullPath = resolve(baseDir, normalizedName);
   const relativePath = relative(baseDir, fullPath);
   const isInsideBaseDir =
-    relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+    relativePath === "" ||
+    (!relativePath.startsWith("..") && !isAbsolute(relativePath));
 
   if (!isInsideBaseDir || !existsSync(fullPath)) {
     throw new Error(`Missing include: ${normalizedName}`);
@@ -223,9 +231,21 @@ function renderVariables(source, context) {
   });
 }
 
-function renderWithContext(source, context, partials, options, includeStack = []) {
+function renderWithContext(
+  source,
+  context,
+  partials,
+  options,
+  includeStack = [],
+) {
   const afterIf = evaluateConditionals(source, context);
-  const afterPartials = renderPartials(afterIf, context, partials, options, includeStack);
+  const afterPartials = renderPartials(
+    afterIf,
+    context,
+    partials,
+    options,
+    includeStack,
+  );
   const afterFileIncludes = renderFileIncludes(
     afterPartials,
     context,
@@ -239,8 +259,8 @@ function renderWithContext(source, context, partials, options, includeStack = []
 function readAllTemplateFiles(rootDir, currentDir = rootDir) {
   if (!rootDir || !existsSync(rootDir)) return [];
 
-  const entries = readdirSync(currentDir, { withFileTypes: true }).sort((left, right) =>
-    left.name.localeCompare(right.name),
+  const entries = readdirSync(currentDir, { withFileTypes: true }).sort(
+    (left, right) => left.name.localeCompare(right.name),
   );
   const files = [];
 
@@ -278,7 +298,10 @@ export function parseFrontmatter(source) {
   return { data, body };
 }
 
-export function buildSkillTemplateContext({ frontmatter = {}, skillDirName = "" } = {}) {
+export function buildSkillTemplateContext({
+  frontmatter = {},
+  skillDirName = "",
+} = {}) {
   const context = { ...frontmatter };
   const skillName = String(frontmatter.name || skillDirName || "").trim();
   const skillDescription = String(frontmatter.description || "").trim();
@@ -337,6 +360,8 @@ export function parseFrontmatterWithManifest(source, skillDir) {
   if (manifest.triggers) merged.triggers = manifest.triggers;
   if (manifest.argument_hint) merged["argument-hint"] = manifest.argument_hint;
   if (manifest.internal != null) merged.internal = manifest.internal;
+  if (manifest.deprecated != null) merged.deprecated = manifest.deprecated;
+  if (manifest.superseded_by) merged["superseded-by"] = manifest.superseded_by;
 
   return { data: merged, body };
 }

package/scripts/lib/team.mjs

@@ -0,0 +1,75 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+function teamContext(env) {
+  const team = env.TFX_TEAM_NAME || "";
+  const taskId = env.TFX_TEAM_TASK_ID || "";
+  if (!team || !taskId) return null;
+  return {
+    team,
+    taskId,
+    agent: env.TFX_TEAM_AGENT_NAME || "agent",
+    lead: env.TFX_TEAM_LEAD_NAME || "team-lead",
+  };
+}
+
+export async function claimTask({ env = process.env, bridge } = {}) {
+  const ctx = teamContext(env);
+  if (!ctx) return { skipped: true };
+  const response = await bridge.claim({
+    team: ctx.team,
+    taskId: ctx.taskId,
+    owner: ctx.agent,
+    status: "in_progress",
+  });
+  if (response?.ok) return { claimed: true };
+  const code = response?.error?.code;
+  const before = response?.error?.details?.task_before ?? {};
+  if (
+    code === "CLAIM_CONFLICT" &&
+    before.owner === ctx.agent &&
+    before.status === "in_progress"
+  ) {
+    return { claimed: true, alreadyClaimed: true };
+  }
+  if (code === "CLAIM_CONFLICT") {
+    return { claimed: false, conflict: true, owner: before.owner ?? null };
+  }
+  return { claimed: false, error: response?.error ?? null };
+}
+
+export async function completeTask({
+  env = process.env,
+  bridge,
+  result = "success",
+  summary = "작업 완료",
+  now = () => new Date().toISOString(),
+} = {}) {
+  const ctx = teamContext(env);
+  if (!ctx) return { skipped: true };
+  const trimmed = String(summary).slice(0, 4096);
+  const response = await bridge.complete({
+    team: ctx.team,
+    taskId: ctx.taskId,
+    agent: ctx.agent,
+    result,
+    summary: trimmed,
+  });
+
+  const resultDir =
+    env.TFX_RESULT_DIR ||
+    join(process.env.HOME || ".", ".claude", "tfx-results", ctx.team);
+  mkdirSync(resultDir, { recursive: true });
+  writeFileSync(
+    join(resultDir, `${ctx.taskId}.json`),
+    `${JSON.stringify({
+      taskId: ctx.taskId,
+      agent: ctx.agent,
+      team: ctx.team,
+      result,
+      summary: trimmed,
+      timestamp: now(),
+    })}\n`,
+  );
+  return { completed: Boolean(response?.ok), response };
+}

package/scripts/lib/timeout.mjs

@@ -0,0 +1,66 @@
+import { spawn } from "node:child_process";
+
+export function timeoutCodeForSignal(signal) {
+  return signal ? 124 : null;
+}
+
+export function runWithTimeout(command, args = [], options = {}) {
+  const {
+    cwd = process.cwd(),
+    env = process.env,
+    input,
+    timeoutMs = 0,
+    stdio = "pipe",
+    spawnFn = spawn,
+  } = options;
+
+  return new Promise((resolve, reject) => {
+    const controller = new AbortController();
+    let timedOut = false;
+    const child = spawnFn(command, args, {
+      cwd,
+      env,
+      stdio,
+      signal: controller.signal,
+    });
+    const stdout = [];
+    const stderr = [];
+    let timer = null;
+
+    if (child.stdout) child.stdout.on("data", (chunk) => stdout.push(chunk));
+    if (child.stderr) child.stderr.on("data", (chunk) => stderr.push(chunk));
+    child.on("error", (err) => {
+      if (timedOut && err.name === "AbortError") return;
+      reject(err);
+    });
+    child.on("exit", (code, signal) => {
+      if (timer) clearTimeout(timer);
+      resolve({
+        code: timedOut ? 124 : (code ?? timeoutCodeForSignal(signal) ?? 1),
+        signal,
+        timedOut,
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8"),
+      });
+    });
+
+    if (timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+        if (child.pid) {
+          try {
+            process.kill(child.pid, "SIGTERM");
+          } catch {
+            // Process already exited.
+          }
+        }
+      }, timeoutMs);
+      timer.unref?.();
+    }
+
+    if (input !== undefined && child.stdin) {
+      child.stdin.end(input);
+    }
+  });
+}