@triflux/core 10.0.0-alpha.1

package/hub/session-fingerprint.mjs

@@ -0,0 +1,352 @@
+import { createHash } from 'node:crypto';
+
+import { normalizePath } from './platform.mjs';
+import { withRetry } from './workers/worker-utils.mjs';
+
+const ADAPTIVE_FINGERPRINT_VERSION = 1;
+const DEFAULT_SCOPE = 'default';
+const META_PREFIX = 'adaptive_fingerprint:';
+const DEFAULT_RETRY_OPTIONS = Object.freeze({
+  maxAttempts: 3,
+  baseDelayMs: 50,
+  maxDelayMs: 250,
+});
+const TIME_WINDOWS = Object.freeze([
+  { name: 'overnight', start: 0, end: 5 },
+  { name: 'morning', start: 6, end: 11 },
+  { name: 'afternoon', start: 12, end: 17 },
+  { name: 'evening', start: 18, end: 23 },
+]);
+const MEMORY_FINGERPRINT_CACHE = new WeakMap();
+
+function clone(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+function toIsoTimestamp(value = Date.now()) {
+  const time = Number.isFinite(Number(value)) ? Number(value) : Date.now();
+  return new Date(time).toISOString();
+}
+
+function toTimestamp(value) {
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string') {
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+
+function normalizeRetryOptions(options = {}) {
+  const maxAttempts = Math.max(1, Number(options.maxAttempts ?? DEFAULT_RETRY_OPTIONS.maxAttempts) || DEFAULT_RETRY_OPTIONS.maxAttempts);
+  const baseDelayMs = Math.max(0, Number(options.baseDelayMs ?? DEFAULT_RETRY_OPTIONS.baseDelayMs) || DEFAULT_RETRY_OPTIONS.baseDelayMs);
+  const maxDelayMs = Math.max(baseDelayMs, Number(options.maxDelayMs ?? DEFAULT_RETRY_OPTIONS.maxDelayMs) || DEFAULT_RETRY_OPTIONS.maxDelayMs);
+  return { maxAttempts, baseDelayMs, maxDelayMs };
+}
+
+function normalizeScope(scope) {
+  const text = String(scope ?? DEFAULT_SCOPE).trim();
+  return text || DEFAULT_SCOPE;
+}
+
+function metaKey(scope) {
+  return `${META_PREFIX}${normalizeScope(scope)}`;
+}
+
+function hashValue(value) {
+  const hash = createHash('sha256');
+  hash.update(JSON.stringify(value));
+  return `sha256:${hash.digest('hex')}`;
+}
+
+function normalizeContextPath(value) {
+  const normalized = normalizePath(String(value ?? ''));
+  return normalized.replace(/\/+/gu, '/').replace(/\/+$/u, '') || '/';
+}
+
+function toRelativePath(targetPath, cwd) {
+  if (!cwd) return targetPath;
+  const base = normalizeContextPath(cwd);
+  if (targetPath === base) return '.';
+  return targetPath.startsWith(`${base}/`) ? targetPath.slice(base.length + 1) : targetPath;
+}
+
+function toUniqueList(values) {
+  const seen = new Set();
+  const next = [];
+  for (const value of values) {
+    if (!value || seen.has(value)) continue;
+    seen.add(value);
+    next.push(value);
+  }
+  return next;
+}
+
+function collectRawPathCandidates(context = {}) {
+  const direct = [context.file_path, context.filePath, context.path, context.target_path, context.targetPath];
+  const fromArrays = [context.files, context.paths, context.targets]
+    .filter(Array.isArray)
+    .flatMap((entry) => entry)
+    .map((entry) => (typeof entry === 'string' ? entry : entry?.path));
+  return [...direct, ...fromArrays].filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
+}
+
+function collectPathPattern(context = {}) {
+  const normalized = toUniqueList(
+    collectRawPathCandidates(context)
+      .map((entry) => normalizeContextPath(entry))
+      .map((entry) => toRelativePath(entry, context.cwd || context.project_root || context.projectRoot)),
+  ).sort();
+
+  const primaryPath = normalized[0] ?? null;
+  const extensions = normalized
+    .map((entry) => entry.split('/').pop() || '')
+    .map((entry) => (entry.includes('.') ? entry.slice(entry.lastIndexOf('.')).toLowerCase() : 'none'));
+  const extensionCounts = extensions.reduce((acc, ext) => ({
+    ...acc,
+    [ext]: (acc[ext] || 0) + 1,
+  }), {});
+
+  return {
+    count: normalized.length,
+    primary_path: primaryPath,
+    sample_paths: normalized.slice(0, 5),
+    extension_counts: extensionCounts,
+    checksum: hashValue(normalized),
+  };
+}
+
+function normalizeWorkType(value) {
+  const text = String(value ?? '').trim().toLowerCase();
+  if (!text) {
+    return { raw: null, normalized: 'general' };
+  }
+  const normalized = text.replace(/\s+/gu, '-').replace(/[^a-z0-9-]/gu, '') || 'general';
+  return { raw: value, normalized };
+}
+
+function collectActivityTimestamps(context = {}, now = Date.now) {
+  const nowValue = typeof now === 'function' ? now() : now;
+  const fromList = [context.activity_timestamps, context.activityTimestamps, context.timestamps]
+    .filter(Array.isArray)
+    .flatMap((entry) => entry)
+    .map(toTimestamp)
+    .filter((entry) => entry != null);
+  const singles = [context.timestamp, context.started_at, context.startedAt]
+    .map(toTimestamp)
+    .filter((entry) => entry != null);
+  return fromList.length || singles.length ? [...fromList, ...singles] : [Number(nowValue)];
+}
+
+function classifyHour(hour) {
+  const safeHour = Number.isFinite(Number(hour)) ? Number(hour) : 0;
+  const matched = TIME_WINDOWS.find((window) => safeHour >= window.start && safeHour <= window.end);
+  return matched?.name || 'overnight';
+}
+
+function buildWindowHistogram(timestamps = []) {
+  const histogram = TIME_WINDOWS.reduce((acc, window) => ({ ...acc, [window.name]: 0 }), {});
+  for (const timestamp of timestamps) {
+    const bucket = classifyHour(new Date(timestamp).getHours());
+    histogram[bucket] = (histogram[bucket] || 0) + 1;
+  }
+  return histogram;
+}
+
+function dominantWindow(histogram) {
+  const sorted = Object.entries(histogram)
+    .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]));
+  return sorted[0]?.[0] || 'overnight';
+}
+
+function resolveTimezoneName(context = {}) {
+  const fromContext = typeof context.timezone === 'string' ? context.timezone.trim() : '';
+  const fromIntl = Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+  return fromContext || fromIntl;
+}
+
+function collectTimezonePattern(context = {}, now = Date.now) {
+  const timestamps = collectActivityTimestamps(context, now);
+  const firstTimestamp = timestamps[0] ?? Date.now();
+  const histogram = buildWindowHistogram(timestamps);
+  return {
+    timezone: resolveTimezoneName(context),
+    offset_minutes: -new Date(firstTimestamp).getTimezoneOffset(),
+    sample_count: timestamps.length,
+    window_histogram: histogram,
+    dominant_window: dominantWindow(histogram),
+  };
+}
+
+function computeFingerprintSignature(input) {
+  const source = {
+    file_checksum: input.path_pattern.checksum,
+    work_type: input.work_type.normalized,
+    timezone: input.timezone_pattern.timezone,
+    dominant_window: input.timezone_pattern.dominant_window,
+  };
+  return hashValue(source);
+}
+
+function getMemoryStoreMap(store) {
+  const current = MEMORY_FINGERPRINT_CACHE.get(store);
+  if (current) return current;
+  const next = new Map();
+  MEMORY_FINGERPRINT_CACHE.set(store, next);
+  return next;
+}
+
+function readFingerprintFromStore(store, scope) {
+  if (!store) return null;
+  if (typeof store.loadAdaptiveFingerprint === 'function') {
+    return store.loadAdaptiveFingerprint(scope);
+  }
+  if (store.db?.prepare) {
+    const row = store.db.prepare('SELECT value FROM _meta WHERE key = ?').get(metaKey(scope));
+    return row?.value ? JSON.parse(row.value) : null;
+  }
+  return clone(getMemoryStoreMap(store).get(normalizeScope(scope)) || null);
+}
+
+function writeFingerprintToStore(store, scope, record) {
+  if (!store) return clone(record);
+  if (typeof store.saveAdaptiveFingerprint === 'function') {
+    return store.saveAdaptiveFingerprint(scope, clone(record));
+  }
+  if (store.db?.prepare) {
+    store.db.prepare('INSERT OR REPLACE INTO _meta (key, value) VALUES (?, ?)')
+      .run(metaKey(scope), JSON.stringify(record));
+    return clone(record);
+  }
+  getMemoryStoreMap(store).set(normalizeScope(scope), clone(record));
+  return clone(record);
+}
+
+function buildHealthSnapshot(base, patch = {}) {
+  return {
+    state: patch.state || base.state || 'healthy',
+    retry: { ...base.retry },
+    last_success_at: patch.last_success_at ?? base.last_success_at ?? null,
+    last_failure_at: patch.last_failure_at ?? base.last_failure_at ?? null,
+    last_error: patch.last_error ?? base.last_error ?? null,
+  };
+}
+
+function createInitialHealth(retryOptions) {
+  return {
+    state: 'healthy',
+    retry: { ...retryOptions },
+    last_success_at: null,
+    last_failure_at: null,
+    last_error: null,
+  };
+}
+
+function resolveNowValue(now) {
+  return typeof now === 'function' ? now() : now;
+}
+
+function mergeFingerprintSnapshot(previous, computed, scope) {
+  return {
+    ...computed,
+    scope,
+    observation_count: (previous?.observation_count || 0) + 1,
+    first_captured_at: previous?.first_captured_at || computed.captured_at,
+  };
+}
+
+function markHealthyHealth(base, now) {
+  return buildHealthSnapshot(base, {
+    state: 'healthy',
+    last_success_at: toIsoTimestamp(resolveNowValue(now)),
+    last_error: null,
+  });
+}
+
+function markDegradedHealth(base, now, error) {
+  return buildHealthSnapshot(base, {
+    state: 'degraded',
+    last_failure_at: toIsoTimestamp(resolveNowValue(now)),
+    last_error: {
+      name: error?.name || 'Error',
+      message: error?.message || 'unknown adaptive fingerprint error',
+    },
+  });
+}
+
+export function buildAdaptiveFingerprint(sessionContext = {}, options = {}) {
+  const now = options.now ?? Date.now;
+  const capturedAt = toIsoTimestamp(resolveNowValue(now));
+  const pathPattern = collectPathPattern(sessionContext);
+  const workType = normalizeWorkType(sessionContext.work_type ?? sessionContext.workType);
+  const timezonePattern = collectTimezonePattern(sessionContext, now);
+  const fingerprintId = computeFingerprintSignature({
+    path_pattern: pathPattern,
+    work_type: workType,
+    timezone_pattern: timezonePattern,
+  });
+
+  return {
+    version: ADAPTIVE_FINGERPRINT_VERSION,
+    captured_at: capturedAt,
+    scope: normalizeScope(sessionContext.scope),
+    fingerprint_id: fingerprintId,
+    path_pattern: pathPattern,
+    work_type: workType,
+    timezone_pattern: timezonePattern,
+  };
+}
+
+export async function loadAdaptiveFingerprint(store, scope = DEFAULT_SCOPE) {
+  const loaded = await Promise.resolve(readFingerprintFromStore(store, scope));
+  return clone(loaded);
+}
+
+export async function saveAdaptiveFingerprint(store, scope, fingerprint, options = {}) {
+  const retryOptions = normalizeRetryOptions(options.retryOptions);
+  const normalizedScope = normalizeScope(scope);
+  const write = async () => Promise.resolve(writeFingerprintToStore(store, normalizedScope, fingerprint));
+  const saved = await withRetry(write, { ...retryOptions });
+  return clone(saved);
+}
+
+export function createAdaptiveFingerprintService(options = {}) {
+  const store = options.store ?? null;
+  const retryOptions = normalizeRetryOptions(options.retryOptions);
+  const now = options.now ?? Date.now;
+  let health = createInitialHealth(retryOptions);
+
+  async function capture(sessionContext = {}) {
+    const computed = buildAdaptiveFingerprint(sessionContext, { now });
+    const scope = normalizeScope(sessionContext.scope ?? computed.scope);
+    const previous = await loadAdaptiveFingerprint(store, scope);
+    const merged = mergeFingerprintSnapshot(previous, computed, scope);
+
+    try {
+      const saved = await saveAdaptiveFingerprint(store, scope, merged, { retryOptions });
+      health = markHealthyHealth(health, now);
+      return saved;
+    } catch (error) {
+      health = markDegradedHealth(health, now, error);
+      throw error;
+    }
+  }
+
+  async function read(scope = DEFAULT_SCOPE) {
+    return loadAdaptiveFingerprint(store, scope);
+  }
+
+  function getHealth() {
+    return clone(health);
+  }
+
+  return Object.freeze({
+    captureFingerprint: capture,
+    computeFingerprint: (sessionContext = {}) => buildAdaptiveFingerprint(sessionContext, { now }),
+    loadFingerprint: read,
+    getHealth,
+  });
+}
+
+export default createAdaptiveFingerprintService;

package/hub/state.mjs

@@ -0,0 +1,245 @@
+import { execSync } from 'node:child_process';
+import { mkdirSync, openSync, closeSync, unlinkSync, writeFileSync, readFileSync, renameSync, existsSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PROJECT_ROOT = fileURLToPath(new URL('..', import.meta.url));
+const STATE_FILE_NAME = 'hub-state.json';
+const LOCK_FILE_NAME = 'hub-start.lock';
+
+let heldLockPath = null;
+let heldLockFd = null;
+let cachedVersionHash = null;
+
+function getStateDir(options = {}) {
+  return options.stateDir || process.env.TFX_HUB_STATE_DIR?.trim() || join(homedir(), '.claude', 'cache', 'tfx-hub');
+}
+
+function getStatePath(options = {}) {
+  return join(getStateDir(options), STATE_FILE_NAME);
+}
+
+function getLockPath(options = {}) {
+  return options.lockPath || join(getStateDir(options), LOCK_FILE_NAME);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isPidAlive(pid) {
+  if (!Number.isFinite(Number(pid)) || Number(pid) <= 0) return false;
+  try {
+    process.kill(Number(pid), 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function parseJson(text, fallback = null) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return fallback;
+  }
+}
+
+function safeReplaceFile(tempPath, targetPath) {
+  try {
+    renameSync(tempPath, targetPath);
+  } catch (error) {
+    if (!['EEXIST', 'EPERM', 'EACCES'].includes(error?.code)) {
+      try { unlinkSync(tempPath); } catch {}
+      throw error;
+    }
+    try { unlinkSync(targetPath); } catch {}
+    renameSync(tempPath, targetPath);
+  }
+}
+
+/**
+ * 허브의 현재 상태(PID, 포트, 버전 등)를 파일에 기록합니다.
+ * 원자적(atomic) 쓰기를 위해 임시 파일을 생성한 후 교체하는 방식을 사용합니다.
+ * 
+ * @param {object} payload - 상태 데이터
+ * @param {number} payload.pid - 허브 프로세스 ID
+ * @param {number} payload.port - 허브 서버 포트
+ * @param {string} payload.version - 허브 버전
+ * @param {string} payload.sessionId - 현재 세션 ID
+ * @param {string} payload.startedAt - 시작 시각 (ISO 8601)
+ * @param {object} [options] - 옵션
+ * @param {string} [options.stateDir] - 상태 파일이 저장될 디렉토리
+ * @returns {object} 기록된 상태 데이터
+ */
+export function writeState({ pid, port, version, sessionId, startedAt }, options = {}) {
+  const stateDir = getStateDir(options);
+  const statePath = getStatePath(options);
+  const tempPath = join(stateDir, `${STATE_FILE_NAME}.${process.pid}.${Date.now()}.tmp`);
+  const payload = { pid, port, version, sessionId, startedAt };
+
+  mkdirSync(stateDir, { recursive: true });
+  writeFileSync(tempPath, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  safeReplaceFile(tempPath, statePath);
+  return payload;
+}
+
+/**
+ * 파일로부터 허브의 현재 상태를 읽어옵니다.
+ * 
+ * @param {object} [options] - 옵션
+ * @param {string} [options.stateDir] - 상태 파일이 저장된 디렉토리
+ * @returns {object|null} 읽어온 상태 데이터 또는 실패 시 null
+ */
+export function readState(options = {}) {
+  const statePath = getStatePath(options);
+  try {
+    if (!existsSync(statePath)) return null;
+    return parseJson(readFileSync(statePath, 'utf8'), null);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 지정된 포트에서 실행 중인 허브 서버의 헬스 체크를 수행합니다.
+ * 
+ * @param {number|string} port - 서버 포트
+ * @param {object} [options] - 옵션
+ * @param {number} [options.timeoutMs=1000] - 요청 타임아웃
+ * @param {string} [options.baseUrl] - 서버 베이스 URL
+ * @returns {Promise<boolean>} 서버 정상 작동 여부
+ */
+export async function isServerHealthy(port, options = {}) {
+  const resolvedPort = Number(port);
+  if (!Number.isFinite(resolvedPort) || resolvedPort <= 0) return false;
+
+  const timeoutMs = Math.max(100, Number(options.timeoutMs) || 1000);
+  const baseUrl = options.baseUrl || `http://127.0.0.1:${resolvedPort}`;
+
+  try {
+    const response = await fetch(`${baseUrl}/health`, {
+      method: 'GET',
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!response.ok) return false;
+    const body = await response.json().catch(() => null);
+    return body?.ok === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 현재 프로젝트의 버전 해시를 생성합니다.
+ * package.json의 버전과 Git commit SHA를 조합합니다.
+ * 
+ * @param {object} [options] - 옵션
+ * @param {boolean} [options.force=false] - 캐시를 무시하고 새로 생성할지 여부
+ * @returns {string} 버전 해시 문자열
+ */
+export function getVersionHash(options = {}) {
+  if (cachedVersionHash && !options.force) return cachedVersionHash;
+
+  const packageJsonPath = join(PROJECT_ROOT, 'package.json');
+  const pkg = parseJson(readFileSync(packageJsonPath, 'utf8'), {});
+  const version = String(pkg?.version || '0.0.0').trim();
+
+  let sha = String(process.env.TFX_HUB_GIT_SHA || '').trim();
+  if (!sha) {
+    try {
+      sha = execSync('git rev-parse --short HEAD', {
+        cwd: PROJECT_ROOT,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        windowsHide: true,
+      }).trim();
+    } catch {
+      sha = '';
+    }
+  }
+
+  cachedVersionHash = sha ? `${version}-${sha}` : version;
+  return cachedVersionHash;
+}
+
+/**
+ * 허브 시작 시 중복 실행을 방지하기 위한 잠금(lock)을 획득합니다.
+ * 이미 실행 중인 다른 프로세스가 있는지 확인하고 유효한 잠금을 획득할 때까지 재시도합니다.
+ * 
+ * @param {object} [options] - 옵션
+ * @param {number} [options.timeoutMs=3000] - 최대 대기 시간
+ * @param {number} [options.pollMs=50] - 재시도 간격
+ * @param {string} [options.lockPath] - 잠금 파일 경로
+ * @returns {Promise<{path: string}>} 잠금 파일 경로
+ * @throws {Error} 타임아웃 내에 잠금을 획득하지 못한 경우
+ */
+export async function acquireLock(options = {}) {
+  if (heldLockFd !== null && heldLockPath) {
+    return { path: heldLockPath };
+  }
+
+  const lockPath = getLockPath(options);
+  const timeoutMs = Math.max(100, Number(options.timeoutMs) || 3000);
+  const pollMs = Math.max(10, Number(options.pollMs) || 50);
+  const deadline = Date.now() + timeoutMs;
+
+  mkdirSync(dirname(lockPath), { recursive: true });
+
+  while (Date.now() <= deadline) {
+    try {
+      const fd = openSync(lockPath, 'wx', 0o600);
+      writeFileSync(fd, `${JSON.stringify({
+        pid: process.pid,
+        createdAt: new Date().toISOString(),
+      }, null, 2)}\n`, 'utf8');
+      heldLockFd = fd;
+      heldLockPath = lockPath;
+      return { path: lockPath };
+    } catch (error) {
+      if (error?.code !== 'EEXIST') {
+        throw error;
+      }
+
+      try {
+        const raw = readFileSync(lockPath, 'utf8');
+        const data = parseJson(raw, {});
+        const stats = statSync(lockPath);
+        const staleByPid = !isPidAlive(data?.pid);
+        const staleByAge = Date.now() - stats.mtimeMs > timeoutMs;
+        if (staleByPid || staleByAge) {
+          try { unlinkSync(lockPath); } catch {}
+          continue;
+        }
+      } catch {}
+
+      await sleep(pollMs);
+    }
+  }
+
+  throw new Error(`hub start lock busy: ${lockPath}`);
+}
+
+/**
+ * 획득했던 잠금을 해제합니다. 잠금 파일을 삭제하고 관련 리소스를 정리합니다.
+ * 
+ * @param {object} [options] - 옵션
+ * @param {string} [options.lockPath] - 명시적인 잠금 파일 경로
+ */
+export function releaseLock(options = {}) {
+  const lockPath = options.lockPath || heldLockPath || getLockPath(options);
+
+  if (heldLockFd !== null) {
+    try { closeSync(heldLockFd); } catch {}
+    heldLockFd = null;
+  }
+
+  try {
+    if (existsSync(lockPath)) unlinkSync(lockPath);
+  } catch {}
+
+  if (!options.lockPath || options.lockPath === heldLockPath) {
+    heldLockPath = null;
+  }
+}

package/hub/team-bridge.mjs

@@ -0,0 +1,25 @@
+// hub/team-bridge.mjs — core ↔ team 디커플링 인터페이스
+// pipe.mjs, tools.mjs가 team/nativeProxy를 직접 참조하지 않도록
+// registry 패턴으로 구현을 주입받는다.
+// remote 미설치 시 graceful no-op 반환.
+
+const noTeam = async () => ({
+  ok: false,
+  error: { code: 'NO_TEAM', message: 'Team module not loaded' },
+});
+
+let _impl = {
+  teamInfo: noTeam,
+  teamTaskList: noTeam,
+  teamTaskUpdate: noTeam,
+  teamSendMessage: noTeam,
+};
+
+export function registerTeamBridge(impl) {
+  _impl = { ..._impl, ...impl };
+}
+
+export function teamInfo(args) { return _impl.teamInfo(args); }
+export function teamTaskList(args) { return _impl.teamTaskList(args); }
+export function teamTaskUpdate(args) { return _impl.teamTaskUpdate(args); }
+export function teamSendMessage(args) { return _impl.teamSendMessage(args); }