@triflux/core 10.1.0 → 10.26.0

package/hub/lib/path-utils.mjs

@@ -0,0 +1,165 @@
+// hub/lib/path-utils.mjs — Windows/POSIX 경로 변환 유틸리티
+
+/**
+ * Windows 경로를 Git Bash 스타일 POSIX 경로로 변환한다.
+ * C:\foo\bar → /c/foo/bar
+ * 이미 POSIX 경로면 그대로 반환.
+ * null/undefined → 빈 문자열
+ * @param {string|null|undefined} windowsPath
+ * @returns {string}
+ */
+export function toPosixPath(windowsPath) {
+  if (windowsPath == null) return "";
+  const p = String(windowsPath);
+  if (!p) return "";
+
+  // 이미 POSIX 경로 (/ 로 시작하거나 드라이브 레터 없음)
+  const winDriveMatch = p.match(/^([A-Za-z]):[/\\](.*)/);
+  if (!winDriveMatch) {
+    // 백슬래시만 있는 상대 경로도 forward slash로 변환
+    return p.replace(/\\/g, "/");
+  }
+
+  const drive = winDriveMatch[1].toLowerCase();
+  const rest = winDriveMatch[2].replace(/\\/g, "/");
+  return `/${drive}/${rest}`;
+}
+
+/**
+ * POSIX 경로(Git Bash 스타일)를 Windows 경로로 변환한다.
+ * /c/foo/bar → C:\foo\bar
+ * 이미 Windows 경로면 그대로 반환.
+ * null/undefined → 빈 문자열
+ * @param {string|null|undefined} posixPath
+ * @returns {string}
+ */
+export function toWindowsPath(posixPath) {
+  if (posixPath == null) return "";
+  const p = String(posixPath);
+  if (!p) return "";
+
+  // 이미 Windows 경로
+  if (/^[A-Za-z]:/.test(p)) {
+    return p.replace(/\//g, "\\");
+  }
+
+  // Git Bash 스타일: /c/foo/bar
+  const gitBashMatch = p.match(/^\/([a-zA-Z])(\/.*)?$/);
+  if (gitBashMatch) {
+    const drive = gitBashMatch[1].toUpperCase();
+    const rest = gitBashMatch[2] ? gitBashMatch[2].replace(/\//g, "\\") : "\\";
+    return `${drive}:${rest}`;
+  }
+
+  return p;
+}
+
+/**
+ * 현재 OS에 맞게 경로를 정규화한다.
+ * win32: backslash, 그 외: forward slash
+ * @param {string|null|undefined} p
+ * @returns {string}
+ */
+export function normalizePath(p) {
+  if (p == null) return "";
+  const str = String(p);
+  if (process.platform === "win32") {
+    return str.replace(/\//g, "\\");
+  }
+  return str.replace(/\\/g, "/");
+}
+
+/**
+ * 쉘 타입에 맞는 경로로 변환한다.
+ * @param {string|null|undefined} path
+ * @param {'git-bash'|'wsl'|'cmd'|'powershell'} shellType
+ * @returns {string}
+ */
+export function resolveShellPath(path, shellType) {
+  if (path == null) return "";
+  const p = String(path);
+
+  switch (shellType) {
+    case "git-bash":
+      return toPosixPath(p);
+
+    case "wsl": {
+      // Git Bash 경로를 먼저 Windows로 변환 후 WSL 형식으로
+      const winPath = /^[A-Za-z]:/.test(p) ? p : toWindowsPath(p);
+      const wslDriveMatch = winPath.match(/^([A-Za-z]):[/\\](.*)/);
+      if (wslDriveMatch) {
+        const drive = wslDriveMatch[1].toLowerCase();
+        const rest = wslDriveMatch[2].replace(/\\/g, "/");
+        return rest ? `/mnt/${drive}/${rest}` : `/mnt/${drive}`;
+      }
+      // 이미 /mnt/ 형식이면 그대로
+      if (p.startsWith("/mnt/")) return p;
+      return p.replace(/\\/g, "/");
+    }
+
+    case "cmd":
+    case "powershell":
+      return toWindowsPath(p);
+
+    default:
+      return p;
+  }
+}
+
+/**
+ * 환경 변수와 플랫폼 정보로 현재 쉘 타입을 추론한다.
+ * @returns {'git-bash'|'wsl'|'cmd'|'powershell'|'unix'}
+ */
+export function detectShellType() {
+  // WSL 감지: WSL_DISTRO_NAME 또는 WSLENV
+  if (process.env.WSL_DISTRO_NAME || process.env.WSLENV) {
+    return "wsl";
+  }
+
+  // Windows 플랫폼
+  if (process.platform === "win32") {
+    const shell = process.env.SHELL || "";
+    const term = process.env.TERM || "";
+    const msystem = process.env.MSYSTEM || "";
+
+    // Git Bash 감지: SHELL=/usr/bin/bash + MSYSTEM=MINGW64 등
+    if (
+      shell.includes("bash") ||
+      msystem.startsWith("MINGW") ||
+      msystem.startsWith("MSYS") ||
+      term === "xterm"
+    ) {
+      return "git-bash";
+    }
+
+    // PowerShell 감지
+    if (process.env.PSModulePath || process.env.PSHOME) {
+      return "powershell";
+    }
+
+    return "cmd";
+  }
+
+  // 비-Windows
+  return "unix";
+}
+
+/**
+ * WSL 경로 여부를 확인한다 (/mnt/ 시작).
+ * @param {string|null|undefined} p
+ * @returns {boolean}
+ */
+export function isWslPath(p) {
+  if (p == null) return false;
+  return String(p).startsWith("/mnt/");
+}
+
+/**
+ * Git Bash 경로 여부를 확인한다 (/c/ 또는 /d/ 등 단일 소문자 드라이브 레터).
+ * @param {string|null|undefined} p
+ * @returns {boolean}
+ */
+export function isGitBashPath(p) {
+  if (p == null) return false;
+  return /^\/[a-zA-Z](\/|$)/.test(String(p));
+}

package/hub/lib/phase-manager.mjs

@@ -0,0 +1,493 @@
+import { existsSync } from "node:fs";
+import {
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  stat,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import os from "node:os";
+import { dirname, join } from "node:path";
+
+/**
+ * @typedef {"Research" | "Strategy" | "Execution" | "Validation"} WorkPhase
+ */
+
+/**
+ * @typedef {"active" | "complete" | "failed"} PhaseStatus
+ */
+
+/**
+ * @typedef {WorkPhase | "complete"} LegacyPhase
+ */
+
+/**
+ * @typedef {object} PhaseRecord
+ * @property {WorkPhase | "complete"} phase
+ * @property {PhaseStatus} phaseStatus
+ * @property {WorkPhase | null} lastPhase
+ */
+
+export const PHASE_ENUM = Object.freeze([
+  "Research",
+  "Strategy",
+  "Execution",
+  "Validation",
+]);
+
+export const PHASE_STATUS = Object.freeze(["active", "complete", "failed"]);
+
+const PHASE_SET = new Set(PHASE_ENUM);
+const PHASE_STATUS_SET = new Set(PHASE_STATUS);
+
+/**
+ * @returns {string}
+ */
+function getHomeDir() {
+  return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is WorkPhase}
+ */
+function isWorkPhase(value) {
+  return PHASE_SET.has(String(value));
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is PhaseStatus}
+ */
+function isPhaseStatus(value) {
+  return PHASE_STATUS_SET.has(String(value));
+}
+
+/**
+ * @param {unknown} value
+ * @returns {WorkPhase | null}
+ */
+function coerceWorkPhase(value) {
+  const phase = coerceLegacyPhase(value);
+  return phase === "complete" ? null : phase;
+}
+
+/**
+ * @param {string} runId
+ * @returns {{fullcycleStatePath: string, phaseStatePath: string}}
+ */
+function getRunPaths(runId) {
+  return {
+    fullcycleStatePath: join(
+      process.cwd(),
+      ".tfx",
+      "fullcycle",
+      runId,
+      "state.json",
+    ),
+    phaseStatePath: join(process.cwd(), ".tfx", "phases", `${runId}.json`),
+  };
+}
+
+/**
+ * @param {string} runId
+ * @returns {string | null}
+ */
+function resolveReadPath(runId) {
+  const { fullcycleStatePath, phaseStatePath } = getRunPaths(runId);
+  if (existsSync(fullcycleStatePath)) return fullcycleStatePath;
+  if (existsSync(phaseStatePath)) return phaseStatePath;
+  return null;
+}
+
+/**
+ * @param {string} runId
+ * @returns {string}
+ */
+function resolveWritePath(runId) {
+  const { fullcycleStatePath, phaseStatePath } = getRunPaths(runId);
+  const fullcycleDir = dirname(fullcycleStatePath);
+
+  if (
+    existsSync(fullcycleStatePath) ||
+    existsSync(fullcycleDir) ||
+    !existsSync(phaseStatePath)
+  ) {
+    return fullcycleStatePath;
+  }
+
+  return phaseStatePath;
+}
+
+/**
+ * @param {string} tempPath
+ * @param {string} targetPath
+ * @returns {Promise<void>}
+ */
+async function safeReplaceFile(tempPath, targetPath) {
+  try {
+    await rename(tempPath, targetPath);
+  } catch (error) {
+    if (!["EEXIST", "EPERM", "EACCES"].includes(error?.code)) {
+      try {
+        await unlink(tempPath);
+      } catch {}
+      throw error;
+    }
+
+    try {
+      await unlink(targetPath);
+    } catch {}
+
+    await rename(tempPath, targetPath);
+  }
+}
+
+/**
+ * @param {string} targetPath
+ * @param {Record<string, unknown>} payload
+ * @returns {Promise<void>}
+ */
+async function writeJsonAtomic(targetPath, payload) {
+  const tempPath = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
+  await mkdir(dirname(targetPath), { recursive: true });
+  await writeFile(tempPath, `${JSON.stringify(payload, null, 2)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  await safeReplaceFile(tempPath, targetPath);
+}
+
+/**
+ * @param {string} targetPath
+ * @param {string} content
+ * @returns {Promise<void>}
+ */
+async function writeTextAtomic(targetPath, content) {
+  const tempPath = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
+  await mkdir(dirname(targetPath), { recursive: true });
+  await writeFile(tempPath, content, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  await safeReplaceFile(tempPath, targetPath);
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Promise<Record<string, unknown> | null>}
+ */
+async function readJsonFile(filePath) {
+  try {
+    const raw = await readFile(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} data
+ * @returns {PhaseRecord | null}
+ */
+function phaseRecordFromData(data) {
+  const explicitPhase = isWorkPhase(data.phase) ? data.phase : null;
+  const explicitStatus = isPhaseStatus(data.phase_status)
+    ? data.phase_status
+    : null;
+  const explicitLastPhase = isWorkPhase(data.last_phase)
+    ? data.last_phase
+    : null;
+  const legacyLastPhase =
+    explicitLastPhase || coerceWorkPhase(data.last_successful_phase);
+
+  if (explicitPhase) {
+    return {
+      phase: explicitPhase,
+      phaseStatus: explicitStatus || "active",
+      lastPhase: legacyLastPhase,
+    };
+  }
+
+  const legacyPhase = coerceLegacyPhase(data.current_phase);
+  if (!legacyPhase) {
+    return null;
+  }
+
+  if (legacyPhase === "complete") {
+    return {
+      phase: legacyLastPhase || "complete",
+      phaseStatus: explicitStatus || "complete",
+      lastPhase: legacyLastPhase,
+    };
+  }
+
+  return {
+    phase: legacyPhase,
+    phaseStatus: explicitStatus || "active",
+    lastPhase: legacyLastPhase,
+  };
+}
+
+/**
+ * @param {WorkPhase | "complete"} phase
+ * @returns {string}
+ */
+function toLegacyPhaseName(phase) {
+  return phase === "complete" ? "complete" : phase.toLowerCase();
+}
+
+/**
+ * @param {Record<string, unknown>} data
+ * @param {PhaseRecord} record
+ * @returns {Record<string, unknown>}
+ */
+function applyPhaseRecord(data, record) {
+  const next = {
+    ...data,
+    phase_status: record.phaseStatus,
+    current_phase: toLegacyPhaseName(record.phase),
+  };
+
+  if (record.phase !== "complete") {
+    next.phase = record.phase;
+  }
+
+  if (record.lastPhase) {
+    next.last_phase = record.lastPhase;
+    next.last_successful_phase = record.lastPhase.toLowerCase();
+  }
+
+  if (record.phaseStatus === "complete" && record.phase !== "complete") {
+    next.last_phase = record.phase;
+    next.last_successful_phase = record.phase.toLowerCase();
+  }
+
+  return next;
+}
+
+/**
+ * @param {string} content
+ * @returns {{lines: string[], bodyLines: string[], eol: string} | null}
+ */
+function parseFrontmatter(content) {
+  const eol = content.includes("\r\n") ? "\r\n" : "\n";
+  const lines = content.split(/\r?\n/);
+
+  if (lines[0] !== "---") {
+    return null;
+  }
+
+  const closingIndex = lines.indexOf("---", 1);
+  if (closingIndex === -1) {
+    return null;
+  }
+
+  return {
+    lines: lines.slice(1, closingIndex),
+    bodyLines: lines.slice(closingIndex + 1),
+    eol,
+  };
+}
+
+/**
+ * @param {string[]} lines
+ * @param {Record<string, string>} fields
+ * @returns {string[]}
+ */
+function upsertFrontmatterLines(lines, fields) {
+  const nextLines = [...lines];
+
+  for (const [key, value] of Object.entries(fields)) {
+    const keyPrefix = `${key}:`;
+    const index = nextLines.findIndex((line) => line.startsWith(keyPrefix));
+
+    if (index >= 0) {
+      nextLines[index] = `${key}: ${value}`;
+      continue;
+    }
+
+    nextLines.push(`${key}: ${value}`);
+  }
+
+  return nextLines;
+}
+
+/**
+ * @param {string} content
+ * @param {Record<string, string>} fields
+ * @returns {string | null}
+ */
+function injectFrontmatterFields(content, fields) {
+  const parsed = parseFrontmatter(content);
+  if (!parsed) {
+    return null;
+  }
+
+  const updatedLines = upsertFrontmatterLines(parsed.lines, fields);
+  return ["---", ...updatedLines, "---", ...parsed.bodyLines].join(parsed.eol);
+}
+
+/**
+ * @param {string} runId
+ * @returns {Promise<PhaseRecord | null>}
+ */
+export async function readPhase(runId) {
+  const statePath = resolveReadPath(runId);
+  if (!statePath) {
+    return null;
+  }
+
+  const data = await readJsonFile(statePath);
+  if (!data) {
+    return null;
+  }
+
+  const record = phaseRecordFromData(data);
+  if (!record) {
+    return null;
+  }
+
+  if (!isWorkPhase(data.phase)) {
+    await writeJsonAtomic(statePath, applyPhaseRecord(data, record));
+  }
+
+  return record;
+}
+
+/**
+ * @param {string} runId
+ * @param {WorkPhase} phase
+ * @param {PhaseStatus} [status="active"]
+ * @returns {Promise<void>}
+ */
+export async function writePhase(runId, phase, status = "active") {
+  if (!isWorkPhase(phase)) {
+    throw new Error(`Invalid phase: ${phase}`);
+  }
+
+  if (!isPhaseStatus(status)) {
+    throw new Error(`Invalid phase status: ${status}`);
+  }
+
+  const statePath = resolveWritePath(runId);
+  const current = (await readJsonFile(statePath)) || {};
+  const next = {
+    ...current,
+    run_id: current.run_id || runId,
+    phase,
+    phase_status: status,
+    current_phase: phase.toLowerCase(),
+  };
+
+  if (status === "complete") {
+    next.last_phase = phase;
+    next.last_successful_phase = phase.toLowerCase();
+  }
+
+  await writeJsonAtomic(statePath, next);
+}
+
+/**
+ * @param {string} runId
+ * @param {string} slug
+ * @returns {Promise<void>}
+ */
+export async function syncToGstack(runId, slug) {
+  const gstackRoot = join(getHomeDir(), ".gstack");
+  if (!existsSync(gstackRoot)) {
+    return;
+  }
+
+  const record = await readPhase(runId);
+  if (!record) {
+    return;
+  }
+
+  const phase = record.phase === "complete" ? record.lastPhase : record.phase;
+  if (!phase) {
+    return;
+  }
+
+  const checkpointsDir = join(gstackRoot, "projects", slug, "checkpoints");
+  if (!existsSync(checkpointsDir)) {
+    return;
+  }
+
+  const entries = await readdir(checkpointsDir, { withFileTypes: true });
+  const markdownFiles = entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+    .map((entry) => join(checkpointsDir, entry.name));
+
+  if (markdownFiles.length === 0) {
+    return;
+  }
+
+  const latestFile = (
+    await Promise.all(
+      markdownFiles.map(async (filePath) => ({
+        filePath,
+        stats: await stat(filePath),
+      })),
+    )
+  ).sort((left, right) => right.stats.mtimeMs - left.stats.mtimeMs)[0]
+    ?.filePath;
+
+  if (!latestFile) {
+    return;
+  }
+
+  const currentContent = await readFile(latestFile, "utf8");
+  const nextContent = injectFrontmatterFields(currentContent, {
+    phase,
+    triflux_run_id: runId,
+  });
+
+  if (!nextContent || nextContent === currentContent) {
+    return;
+  }
+
+  await writeTextAtomic(latestFile, nextContent);
+}
+
+/**
+ * @param {unknown} text
+ * @returns {LegacyPhase | null}
+ */
+export function coerceLegacyPhase(text) {
+  if (text == null) {
+    return null;
+  }
+
+  const value = String(text).trim();
+  if (!value) {
+    return null;
+  }
+
+  if (/^complete$/i.test(value)) {
+    return "complete";
+  }
+
+  if (/interview|research|phase1/i.test(value)) {
+    return "Research";
+  }
+
+  if (/plan|strategy|phase2/i.test(value)) {
+    return "Strategy";
+  }
+
+  if (/exec|ship|phase3|phase4/i.test(value)) {
+    return "Execution";
+  }
+
+  if (/valid|qa|review|phase5/i.test(value)) {
+    return "Validation";
+  }
+
+  return null;
+}