@triflux/remote 10.1.0 → 10.26.0

package/scripts/lib/psmux-info.mjs

@@ -0,0 +1,224 @@
+import { execFileSync } from "node:child_process";
+
+export const PSMUX_RECOMMENDED_VERSION = "3.3.1";
+export const PSMUX_REQUIRED_COMMANDS = [
+  "new-session",
+  "attach-session",
+  "kill-session",
+  "capture-pane",
+];
+
+export const PSMUX_OPTIONAL_COMMANDS = ["detach-client"];
+
+// Windows 패키지 매니저 — winget/scoop/choco 는 Windows 전용
+export const PSMUX_INSTALL_COMMANDS = [
+  "winget install psmux",
+  "scoop install psmux",
+  "choco install psmux",
+  "cargo install psmux",
+];
+
+export const PSMUX_UPDATE_COMMANDS = [
+  "winget upgrade psmux",
+  "scoop update psmux",
+  "choco upgrade psmux",
+  "cargo install psmux --force",
+];
+
+// 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 는 선택형이다. 따라서 macOS/Linux 에서 "psmux 미설치"는 fallback 사유가
+// 아니며, tmux 까지 없을 때만 native/in-process fallback 을 고려한다.
+export const PSMUX_FALLBACK_NOTE_DARWIN =
+  "macOS 에서는 tmux 가 표준 멀티플렉서이며, " +
+  "psmux 미설치는 fallback 사유가 아닙니다. tmux 도 없을 때만 in-process/native fallback 을 사용합니다.";
+
+export const PSMUX_FALLBACK_NOTE_LINUX =
+  "Linux 에서는 tmux 가 표준 멀티플렉서이며, " +
+  "psmux 미설치는 fallback 사유가 아닙니다. tmux 도 없을 때만 in-process/native 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 = "",
+  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 = "",
+  platform = process.platform,
+) {
+  return formatPsmuxCommandList(getPsmuxUpdateCommandsFor(platform), indent);
+}
+
+export function parsePsmuxVersion(output = "") {
+  const match = String(output).match(/psmux\s+v?(\d+\.\d+\.\d+)/i);
+  return match?.[1] || null;
+}
+
+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);
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] > right[index]) return 1;
+    if (left[index] < right[index]) return -1;
+  }
+  return 0;
+}
+
+export function isRecommendedPsmuxVersion(version) {
+  if (!version) return false;
+  return compareSemver(version, PSMUX_RECOMMENDED_VERSION) >= 0;
+}
+
+export function probePsmuxSupport(options = {}) {
+  const execFileSyncFn = options.execFileSyncFn || execFileSync;
+  const bin = options.bin || "psmux";
+
+  try {
+    const versionOutput = execFileSyncFn(bin, ["-V"], {
+      encoding: "utf8",
+      timeout: 2000,
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+    });
+    const version = parsePsmuxVersion(versionOutput);
+
+    let helpOutput = "";
+    try {
+      helpOutput = execFileSyncFn(bin, ["--help"], {
+        encoding: "utf8",
+        timeout: 2000,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+      });
+    } catch {
+      helpOutput = "";
+    }
+
+    const missingCommands = PSMUX_REQUIRED_COMMANDS.filter(
+      (command) => !helpOutput?.includes(command),
+    );
+    const missingOptionalCommands = PSMUX_OPTIONAL_COMMANDS.filter(
+      (command) => !helpOutput?.includes(command),
+    );
+
+    return {
+      ok: missingCommands.length === 0,
+      installed: true,
+      version,
+      recommendedVersion: PSMUX_RECOMMENDED_VERSION,
+      recommended: isRecommendedPsmuxVersion(version),
+      missingCommands,
+      missingOptionalCommands,
+      hasHelp: helpOutput.length > 0,
+      installHint: formatPsmuxInstallGuidance("  "),
+      updateHint: formatPsmuxUpdateGuidance("  "),
+    };
+  } catch {
+    return {
+      ok: false,
+      installed: false,
+      version: null,
+      recommendedVersion: PSMUX_RECOMMENDED_VERSION,
+      recommended: false,
+      missingCommands: [...PSMUX_REQUIRED_COMMANDS],
+      missingOptionalCommands: [...PSMUX_OPTIONAL_COMMANDS],
+      hasHelp: false,
+      installHint: formatPsmuxInstallGuidance("  "),
+      updateHint: formatPsmuxUpdateGuidance("  "),
+    };
+  }
+}
+
+export function probePrimaryMultiplexerSupport(options = {}) {
+  const platform = options.platform || process.platform;
+  const execFileSyncFn = options.execFileSyncFn || execFileSync;
+
+  if (platform === "win32") {
+    return {
+      kind: "psmux",
+      ...probePsmuxSupport(options),
+    };
+  }
+
+  const bin = options.bin || "tmux";
+  try {
+    const versionOutput = execFileSyncFn(bin, ["-V"], {
+      encoding: "utf8",
+      timeout: 2000,
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+    });
+    return {
+      ok: true,
+      installed: true,
+      kind: "tmux",
+      version: String(versionOutput || "").trim() || null,
+      recommendedVersion: null,
+      recommended: true,
+      missingCommands: [],
+      missingOptionalCommands: [],
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      installed: false,
+      kind: "tmux",
+      version: null,
+      recommendedVersion: null,
+      recommended: false,
+      missingCommands: ["tmux"],
+      missingOptionalCommands: [],
+      error: error?.message || String(error),
+    };
+  }
+}

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

@@ -0,0 +1,226 @@
+import { existsSync, readFileSync, statSync } from "fs";
+import { basename, dirname, isAbsolute, resolve } from "path";
+
+const URL_LIKE_RE = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//u;
+const WINDOWS_ABS_RE = /^[a-zA-Z]:[\\/]/u;
+
+function normalizeMarkdownTarget(raw) {
+  const trimmed = String(raw || "").trim();
+  const match = /^<?([^>\s]+)>?(?:\s+["'][^"']*["'])?$/u.exec(trimmed);
+  return match ? match[1] : trimmed;
+}
+
+function sanitizeToken(raw) {
+  let token = String(raw || "").trim();
+  if (!token) return "";
+  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 === "~") return false;
+
+  const hasPathSeparator = token.includes("/") || token.includes("\\");
+  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
+  );
+}
+
+export function extractExplicitFileTokens(text) {
+  const content = String(text || "");
+  const candidates = [];
+
+  for (const match of content.matchAll(/\[[^\]]+\]\(([^)\n]+)\)/gu)) {
+    candidates.push(normalizeMarkdownTarget(match[1]));
+  }
+  for (const match of content.matchAll(/`([^`\n]+)`/gu)) {
+    candidates.push(match[1]);
+  }
+  for (const match of content.matchAll(/"([^"\n]+)"/gu)) {
+    candidates.push(match[1]);
+  }
+  for (const match of content.matchAll(/'([^'\n]+)'/gu)) {
+    candidates.push(match[1]);
+  }
+
+  const unique = new Set();
+  for (const raw of candidates) {
+    const token = sanitizeToken(raw);
+    if (!isLikelyPathToken(token)) continue;
+    unique.add(token);
+  }
+
+  return Array.from(unique);
+}
+
+function validateTransferFile(filePath, maxBytes) {
+  if (!existsSync(filePath)) {
+    throw new Error(`referenced file not found: ${filePath}`);
+  }
+  const stats = statSync(filePath);
+  if (!stats.isFile()) {
+    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}`,
+    );
+  }
+  return stats.size;
+}
+
+function resolveReferencePath(token, handoffAbsPath, cwd) {
+  if (WINDOWS_ABS_RE.test(token) || isAbsolute(token)) {
+    return resolve(token);
+  }
+
+  if (token.startsWith("~/") || token.startsWith("~\\")) {
+    if (!process.env.HOME && !process.env.USERPROFILE) {
+      return null;
+    }
+    const homeDir = process.env.HOME || process.env.USERPROFILE;
+    return resolve(homeDir, token.slice(2));
+  }
+
+  const handoffDir = dirname(handoffAbsPath);
+  const primary = resolve(handoffDir, token);
+  if (existsSync(primary)) {
+    return primary;
+  }
+
+  const fallback = resolve(cwd, token);
+  return existsSync(fallback) ? fallback : primary;
+}
+
+function toRemotePath(stageRoot, relativePath) {
+  const root = String(stageRoot).replace(/\\/gu, "/").replace(/\/+$/u, "");
+  const rel = String(relativePath).replace(/\\/gu, "/").replace(/^\/+/, "");
+  return `${root}/${rel}`;
+}
+
+export function buildRemoteTransferPlan(options = {}) {
+  const {
+    cwd = process.cwd(),
+    handoffPath = null,
+    maxBytes,
+    remoteStageRoot,
+    userPrompt = null,
+    maxReferenceFiles = 32,
+  } = options;
+
+  if (!handoffPath) {
+    return {
+      prompt: userPrompt || "",
+      replacements: [],
+      stagedHandoffPath: null,
+      transfers: [],
+    };
+  }
+
+  if (!remoteStageRoot) {
+    throw new Error("remoteStageRoot is required when handoffPath is provided");
+  }
+
+  if (!Number.isFinite(maxBytes) || maxBytes <= 0) {
+    throw new Error("maxBytes must be a positive number");
+  }
+
+  const absoluteHandoffPath = resolve(cwd, handoffPath);
+  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 tokens = extractExplicitFileTokens(handoffContent);
+  if (tokens.length > maxReferenceFiles) {
+    throw new Error(
+      `too many referenced files: ${tokens.length} (max ${maxReferenceFiles})`,
+    );
+  }
+
+  const stagedByLocalPath = new Map();
+  const replacements = [];
+  let fileIndex = 0;
+
+  for (const token of tokens) {
+    const resolvedPath = resolveReferencePath(token, absoluteHandoffPath, cwd);
+    validateTransferFile(resolvedPath, maxBytes);
+
+    if (!stagedByLocalPath.has(resolvedPath)) {
+      fileIndex += 1;
+      const stagedPath = toRemotePath(
+        remoteStageRoot,
+        `refs/${String(fileIndex).padStart(2, "0")}-${basename(resolvedPath)}`,
+      );
+      stagedByLocalPath.set(resolvedPath, stagedPath);
+      transfers.push({
+        localPath: resolvedPath,
+        remotePath: stagedPath,
+        type: "reference",
+      });
+    }
+
+    replacements.push({
+      token,
+      stagedPath: stagedByLocalPath.get(resolvedPath),
+    });
+  }
+
+  const replacementEntries = Array.from(
+    replacements
+      .reduce((map, entry) => map.set(entry.token, entry.stagedPath), new Map())
+      .entries(),
+  ).sort((a, b) => b[0].length - a[0].length);
+
+  let rewrittenHandoff = handoffContent;
+  for (const [token, stagedPath] of replacementEntries) {
+    rewrittenHandoff = rewrittenHandoff.split(token).join(stagedPath);
+  }
+
+  const prefix = `Staged handoff file: ${stagedHandoffPath}`;
+  let prompt = rewrittenHandoff ? `${prefix}\n\n${rewrittenHandoff}` : prefix;
+
+  if (userPrompt) {
+    prompt = `${prompt}\n\n---\n\n${userPrompt}`;
+  }
+
+  return {
+    prompt,
+    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;
+}