triflux 10.2.1 → 10.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "10.2.1",
+  "version": "10.3.0",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {
@@ -44,11 +44,11 @@
     "lint": "biome check .",
     "lint:fix": "biome check --fix .",
     "health": "npm test && npm run lint",
-    "test": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=1 \"tests/**/*.test.mjs\" \"scripts/__tests__/**/*.test.mjs\"",
-    "test:unit": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=1 tests/unit/**/*.test.mjs",
-    "test:integration": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=1 tests/integration/**/*.test.mjs",
+    "test": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=8 \"tests/**/*.test.mjs\" \"scripts/__tests__/**/*.test.mjs\"",
+    "test:unit": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=8 tests/unit/**/*.test.mjs",
+    "test:integration": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=8 tests/integration/**/*.test.mjs",
     "test:route-smoke": "node scripts/test-lock.mjs --test scripts/test-tfx-route-no-claude-native.mjs",
-    "test:contract": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=1 tests/contract/**/*.test.mjs",
+    "test:contract": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=8 tests/contract/**/*.test.mjs",
     "gen:skill-docs": "node scripts/gen-skill-docs.mjs",
     "gen:skill-manifest": "node scripts/gen-skill-manifest.mjs"
   },

package/scripts/codex-gateway-preflight.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// scripts/codex-gateway-preflight.mjs — Codex MCP 초기화 시 gateway 자동 기동
+// Codex config.toml에 MCP 서버로 등록되면, Codex 시작 시 이 스크립트가 먼저 실행되어
+// gateway가 alive인지 확인하고 죽었으면 기동한다.
+// 실제 MCP 기능은 없음 (no-op). 역할은 gateway 보장뿐.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tmpdir } from 'node:os';
+
+const PLUGIN_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const PROBE_PORT = 8100;
+const PROBE_TIMEOUT_MS = 2000;
+const STARTUP_WAIT_MS = 6000;
+const POLL_MS = 500;
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5분
+const CACHE_FILE = join(tmpdir(), 'tfx-gateway-alive.json');
+
+function readCache() {
+  try {
+    if (!existsSync(CACHE_FILE)) return null;
+    const data = JSON.parse(readFileSync(CACHE_FILE, 'utf8'));
+    if (Date.now() - data.ts < CACHE_TTL_MS) return data;
+  } catch { /* ignore */ }
+  return null;
+}
+
+function writeCache() {
+  try {
+    writeFileSync(CACHE_FILE, JSON.stringify({ ts: Date.now(), alive: true }));
+  } catch { /* ignore */ }
+}
+
+async function isGatewayAlive() {
+  // B) Preflight 캐시: 5분 이내 확인했으면 프로브 스킵
+  const cached = readCache();
+  if (cached) return true;
+
+  try {
+    const res = await fetch(`http://127.0.0.1:${PROBE_PORT}/healthz`, {
+      signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+    });
+    if (res.ok) { writeCache(); return true; }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+async function startGateway() {
+  const script = join(PLUGIN_ROOT, 'scripts', 'mcp-gateway-start.mjs');
+  if (!existsSync(script)) {
+    process.stderr.write('[gateway-preflight] mcp-gateway-start.mjs not found\n');
+    return false;
+  }
+
+  const { execSync } = await import('node:child_process');
+  try {
+    execSync(`node "${script}"`, {
+      stdio: 'ignore',
+      timeout: STARTUP_WAIT_MS + 2000,
+      cwd: PLUGIN_ROOT,
+    });
+  } catch {
+    // gateway-start는 자체 프로세스로 spawn하므로 parent는 바로 종료 가능
+  }
+
+  // 헬스체크 대기
+  const deadline = Date.now() + STARTUP_WAIT_MS;
+  while (Date.now() < deadline) {
+    if (await isGatewayAlive()) return true;
+    await new Promise((r) => setTimeout(r, POLL_MS));
+  }
+  return false;
+}
+
+// ── MCP stdio 프로토콜 (no-op server) ──
+
+async function main() {
+  // 1) gateway 보장
+  const alive = await isGatewayAlive();
+  if (!alive) {
+    process.stderr.write('[gateway-preflight] gateway down, starting...\n');
+    const ok = await startGateway();
+    process.stderr.write(ok
+      ? '[gateway-preflight] gateway started\n'
+      : '[gateway-preflight] gateway start failed\n');
+  }
+
+  // 2) MCP JSON-RPC stdio — initialize 핸드셰이크만 처리하고 idle 유지
+  const { createInterface } = await import('node:readline');
+  const rl = createInterface({ input: process.stdin });
+
+  rl.on('line', (line) => {
+    try {
+      const msg = JSON.parse(line);
+      if (msg.method === 'initialize') {
+        const response = {
+          jsonrpc: '2.0',
+          id: msg.id,
+          result: {
+            protocolVersion: '2024-11-05',
+            capabilities: {},
+            serverInfo: { name: 'tfx-gateway-preflight', version: '1.0.0' },
+          },
+        };
+        process.stdout.write(JSON.stringify(response) + '\n');
+      } else if (msg.method === 'notifications/initialized') {
+        // ack, no response needed
+      } else if (msg.method === 'tools/list') {
+        process.stdout.write(JSON.stringify({
+          jsonrpc: '2.0',
+          id: msg.id,
+          result: { tools: [] },
+        }) + '\n');
+      } else if (msg.id !== undefined) {
+        // unknown method with id — respond empty
+        process.stdout.write(JSON.stringify({
+          jsonrpc: '2.0',
+          id: msg.id,
+          result: {},
+        }) + '\n');
+      }
+    } catch {
+      // ignore parse errors
+    }
+  });
+
+  rl.on('close', () => process.exit(0));
+}
+
+main();

package/scripts/codex-mcp-gateway-sync.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+// scripts/codex-mcp-gateway-sync.mjs — Codex config.toml MCP를 gateway SSE로 전환
+// Usage: node codex-mcp-gateway-sync.mjs [--enable|--disable|--status]
+//
+// 문제: Codex CLI가 매 호출마다 MCP 서버를 stdio로 spawn → 좀비 Node.js 프로세스
+// 해결: mcp-gateway-start.mjs의 싱글톤 SSE 데몬을 재사용하도록 config.toml 전환
+//
+// before: [mcp_servers.context7]
+//         command = "npx"
+//         args = ["-y", "@upstash/context7-mcp@latest"]
+//
+// after:  [mcp_servers.context7]
+//         url = "http://127.0.0.1:8100/sse"
+
+import { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+import { SERVERS } from './mcp-gateway-start.mjs';
+
+const CODEX_CONFIG = join(homedir(), '.codex', 'config.toml');
+const BACKUP_SUFFIX = '.pre-gateway.bak';
+
+// gateway 서버 → SSE URL 매핑
+const GATEWAY_MAP = new Map(
+  SERVERS.map((s) => [s.name, `http://127.0.0.1:${s.port}/sse`]),
+);
+
+// stdio 정의를 보존해야 하는 MCP 서버 (gateway 대상 아님)
+const KEEP_STDIO = new Set([
+  'omx_state', 'omx_memory', 'omx_code_intel', 'omx_trace', 'omx_team_run',
+  'tfx-hub',
+]);
+
+function parseTomlMcpServers(content) {
+  const servers = new Map();
+  const re = /^\[mcp_servers\.([^\]]+)\]\s*$/gm;
+  let match;
+
+  while ((match = re.exec(content)) !== null) {
+    const name = match[1];
+    const startIdx = match.index + match[0].length;
+
+    // 다음 [section] 또는 파일 끝까지가 이 서버의 범위
+    const nextSection = content.indexOf('\n[', startIdx);
+    const block = content.slice(startIdx, nextSection === -1 ? undefined : nextSection).trim();
+
+    const hasUrl = /^url\s*=/m.test(block);
+    const hasCommand = /^command\s*=/m.test(block);
+
+    servers.set(name, { block, hasUrl, hasCommand, startIdx, headerIdx: match.index });
+  }
+
+  return servers;
+}
+
+function buildSseEntry(name, url) {
+  return `[mcp_servers.${name}]\nurl = "${url}"\n`;
+}
+
+function buildStdioEntry(name, block) {
+  return `[mcp_servers.${name}]\n${block}\n`;
+}
+
+// ── enable: stdio → SSE ──
+
+export function enableGateway() {
+  if (!existsSync(CODEX_CONFIG)) {
+    console.log('[SKIP] ~/.codex/config.toml not found');
+    return { changed: 0, skipped: 0 };
+  }
+
+  const original = readFileSync(CODEX_CONFIG, 'utf8');
+  const servers = parseTomlMcpServers(original);
+
+  // 백업 (최초 1회만)
+  const backupPath = CODEX_CONFIG + BACKUP_SUFFIX;
+  if (!existsSync(backupPath)) {
+    copyFileSync(CODEX_CONFIG, backupPath);
+    console.log(`[BACKUP] ${backupPath}`);
+  }
+
+  let content = original;
+  let changed = 0;
+  let skipped = 0;
+
+  for (const [name, url] of GATEWAY_MAP) {
+    const srv = servers.get(name);
+
+    if (!srv) {
+      // 서버 미등록 → SSE entry 추가
+      content += `\n${buildSseEntry(name, url)}`;
+      changed++;
+      console.log(`[ADD] ${name} → ${url}`);
+      continue;
+    }
+
+    if (srv.hasUrl) {
+      // 이미 URL 기반 → 스킵
+      skipped++;
+      continue;
+    }
+
+    if (srv.hasCommand) {
+      // stdio → SSE 전환: 기존 블록을 URL로 교체
+      const oldSection = `[mcp_servers.${name}]\n${srv.block}`;
+      const newSection = buildSseEntry(name, url).trim();
+      content = content.replace(oldSection, newSection);
+      changed++;
+      console.log(`[CONVERT] ${name}: stdio → ${url}`);
+    }
+  }
+
+  // preflight MCP 서버 등록 — Codex 시작 시 gateway 자동 기동 보장
+  const preflightName = 'tfx-gateway-preflight';
+  if (!servers.has(preflightName)) {
+    const resolvedPath = join(dirname(fileURLToPath(import.meta.url)), 'codex-gateway-preflight.mjs')
+      .replace(/\\/g, '\\\\');
+    content += `\n[mcp_servers.${preflightName}]\ncommand = "node"\nargs = ["${resolvedPath}"]\nenabled = true\nstartup_timeout_sec = 10\n`;
+    changed++;
+    console.log(`[ADD] ${preflightName} — Codex 시작 시 gateway 자동 기동`);
+  }
+
+  if (changed > 0) {
+    writeFileSync(CODEX_CONFIG, content, 'utf8');
+    console.log(`\n[DONE] ${changed} servers converted, ${skipped} already SSE`);
+  } else {
+    console.log(`\n[DONE] No changes needed (${skipped} already SSE)`);
+  }
+
+  return { changed, skipped };
+}
+
+// ── disable: SSE → stdio 복원 ──
+
+export function disableGateway() {
+  const backupPath = CODEX_CONFIG + BACKUP_SUFFIX;
+  if (!existsSync(backupPath)) {
+    console.log('[SKIP] No backup found — nothing to restore');
+    return false;
+  }
+
+  copyFileSync(backupPath, CODEX_CONFIG);
+  console.log('[RESTORE] config.toml restored from pre-gateway backup');
+  return true;
+}
+
+// ── status: 현재 상태 확인 ──
+
+export function getStatus() {
+  if (!existsSync(CODEX_CONFIG)) {
+    return { exists: false, servers: [] };
+  }
+
+  const content = readFileSync(CODEX_CONFIG, 'utf8');
+  const servers = parseTomlMcpServers(content);
+  const result = [];
+
+  for (const [name, url] of GATEWAY_MAP) {
+    const srv = servers.get(name);
+    if (!srv) {
+      result.push({ name, mode: 'missing', url });
+    } else if (srv.hasUrl) {
+      result.push({ name, mode: 'sse', url });
+    } else {
+      result.push({ name, mode: 'stdio', url });
+    }
+  }
+
+  return { exists: true, servers: result };
+}
+
+// ── CLI ──
+
+const arg = process.argv[2];
+
+if (arg === '--enable') {
+  enableGateway();
+} else if (arg === '--disable') {
+  disableGateway();
+} else if (arg === '--status') {
+  const { exists, servers } = getStatus();
+  if (!exists) {
+    console.log('config.toml not found');
+    process.exit(1);
+  }
+  console.log('\nCodex MCP Gateway Status:');
+  console.log('─'.repeat(50));
+  for (const s of servers) {
+    const icon = s.mode === 'sse' ? '✅' : s.mode === 'stdio' ? '⚠️' : '❌';
+    console.log(`${icon} ${s.name.padEnd(15)} ${s.mode.padEnd(8)} ${s.mode === 'stdio' ? '← zombie risk' : ''}`);
+  }
+} else {
+  console.log('Usage: codex-mcp-gateway-sync.mjs [--enable|--disable|--status]');
+  console.log('  --enable   Convert stdio MCP servers to SSE gateway URLs');
+  console.log('  --disable  Restore original stdio config from backup');
+  console.log('  --status   Show current MCP connection mode per server');
+}

package/skills/star-prompt/SKILL.md

@@ -1,122 +1,222 @@
 ---
 name: star-prompt
 description: >-
-  CLI 프로젝트의 setup/postinstall 흐름에 GitHub 스타 요청 프롬프트를 추가한다.
-  gh CLI 인증 확인 → 이미 스타 여부 감지 → 인터랙티브 confirm → gh API로 자동 스타.
-  Apple 스타일 UX 카피 포함. 'star prompt', '스타 요청', '리포 스타', 'star request',
-  '깃헙 스타 넣어줘', 'star 눌러달라고', '응원 요청' 같은 요청에 사용한다.
+  CLI 프로젝트의 setup/postinstall 흐름에 GitHub 스타 요청을 추가한다.
+  기본: 모달 차단형 (AskUserQuestion). --soft: 부드러운 confirm 모드.
+  gh CLI 인증 확인 → 이미 스타 여부 감지 → 선택 강제 → gh API로 자동 스타.
+  'star prompt', '스타 요청', '리포 스타', 'star request', '깃헙 스타 넣어줘',
+  'star 눌러달라고', '응원 요청' 같은 요청에 사용한다.
 ---
 
 # tfx-star-prompt — GitHub Star Request Prompt
 
-CLI 도구의 setup 완료 시점에 GitHub 리포 스타를 요청하는 프롬프트를 추가한다.
-사용자 경험을 해치지 않으면서, 이미 스타한 사용자에겐 감사를 표하고, 아직 안 한 사용자에겐 부담 없이 한 번 물어본다.
+CLI 도구의 setup/postinstall 완료 시점에 GitHub 리포 스타 요청을 추가한다.
+기본 모드는 aggressive(모달 차단형)이며, `--soft`를 전달하면 기존 부드러운 confirm 모드로 폴백한다.
+CI/비인터랙티브 환경에서는 자동으로 soft 모드로 강등한다.
 
 ## 동작 흐름
 
 ```
-gh auth status ─── 실패 → URL만 표시 (비인터랙티브 폴백)
+detectInteractive() ─── false → soft 모드 강제
+       │
+       ✓ true
+       │
+gh --version ─── 실패 → URL만 표시
+       │
+       ✓ 설치됨
+       │
+gh auth status ─── 실패 → URL만 표시
        │
        ✓ 인증됨
        │
-gh api user/starred/{owner}/{repo} ─── 성공 → "이미 함께하고 계시군요. ⭐"
+gh api user/starred/{owner}/{repo}
+       ├─ 성공 → "이미 함께하고 계시군요. ⭐" + markPrompted()
+       ├─ 404  → 미스타로 진행
+       └─ 그 외 에러 → 프롬프트 없이 URL만 표시 (마커 남기지 않음)
        │
        ✗ 미스타
        │
-confirm("⭐ 하나가 큰 차이를 만듭니다.") ─── N → URL 조용히 표시
+이미 프롬프트 본 유저(마커 존재)면 즉시 스킵
+       │
+aggressive 기본: AskUserQuestion([예, 누를게요] / [아니오]) 블로킹 선택
+soft(--soft): confirm("⭐ 하나가 큰 차이를 만듭니다.")
+       │
+       ├─ 아니오 → aggressive: 안내 + URL / soft: URL만 + markPrompted()
+       └─ 예
        │
        Y
        │
-gh api -X PUT /user/starred/{owner}/{repo} → "함께해 주셔서 감사합니다. ⭐"
+gh api -X PUT /user/starred/{owner}/{repo}
+       ├─ 성공 → aggressive: "감사합니다! 여러분의 ⭐가 프로젝트를 성장시킵니다."
+       │         soft: "함께해 주셔서 감사합니다. ⭐"
+       └─ 실패 → URL 폴백
        │
-       실패 → URL 폴백
+모든 프롬프트 완료 경로는 markPrompted() 호출
 ```
 
 ## 구현 패턴
 
-### 인터랙티브 (TUI / readline confirm)
+### 유틸리티 계약
+
+- `ok(message)`: 성공 메시지 출력(초록/강조 톤)
+- `info(message)`: 일반 안내 메시지 출력
+- `warn(message)`: 경고/실패 폴백 메시지 출력
+- `confirm(message, defaultValue)`: soft 모드용 Y/n 확인
+- `askUserQuestion({ question, options })`: aggressive 모달 선택 UI
+  - 옵션은 정확히 `[예, 누를게요]`, `[아니오]`
+  - 선택 전까지 흐름을 블로킹한다
+
+### 전체 `starRequest` 교체 패턴
 
-setup 위저드 완료 후 호출. `confirm()` 으로 Y/n 입력 받고 `gh api`로 자동 스타.
+아래 패턴으로 기존 `starRequest` 함수를 전면 교체한다.
 
 ```javascript
-async function starRequest() {
-  let ghOk = false;
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+function detectInteractive() {
+  if (!process.stdout.isTTY) return false;
+  if (process.env.CI) return false;
+  if (process.env.TERM === "dumb") return false;
+  return true;
+}
+
+function runGh(args) {
+  return execFileSync("gh", args, {
+    timeout: 10000,
+    encoding: "utf8",
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+}
+
+function getHttpStatus(error) {
+  const out = [error?.stdout, error?.stderr].filter(Boolean).join("\n");
+  const match = out.match(/HTTP\s+(\d{3})/i) || out.match(/\b(\d{3})\b/);
+  return match ? Number(match[1]) : null;
+}
+
+export async function starRequest({
+  owner,
+  repo,
+  soft = false,
+  askUserQuestion,
+  confirm,
+  ok,
+  info,
+  warn,
+}) {
+  const repoUrl = `https://github.com/${owner}/${repo}`;
+  const interactive = detectInteractive();
+  const useSoft = soft || !interactive;
+
+  const MARKER_DIR = path.join(os.homedir(), ".config", "star-prompt");
+  const MARKER = path.join(MARKER_DIR, `${owner}-${repo}.prompted`);
+
+  const markPrompted = () => {
+    fs.mkdirSync(MARKER_DIR, { recursive: true });
+    fs.writeFileSync(MARKER, new Date().toISOString(), "utf8");
+  };
+
+  if (fs.existsSync(MARKER)) return;
+
   try {
-    execFileSync("gh", ["auth", "status"], {
-      timeout: 5000, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"],
-    });
-    ghOk = true;
-  } catch {}
+    runGh(["--version"]);
+  } catch {
+    info(repoUrl);
+    return;
+  }
 
-  if (!ghOk) {
-    // gh 미설치/미인증 — URL만 표시
-    info(`⭐ 하나가 큰 차이를 만듭니다. https://github.com/{owner}/{repo}`);
+  try {
+    runGh(["auth", "status"]);
+  } catch {
+    info(repoUrl);
     return;
   }
 
   let alreadyStarred = false;
   try {
-    execFileSync("gh", ["api", "user/starred/{owner}/{repo}"], {
-      timeout: 5000, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"],
-    });
+    runGh(["api", `user/starred/${owner}/${repo}`]);
     alreadyStarred = true;
-  } catch {}
+  } catch (error) {
+    const status = getHttpStatus(error);
+    if (status === 404) {
+      alreadyStarred = false;
+    } else {
+      // API 에러(404 외): 프롬프트 없이 URL만 출력, 마커 미기록
+      warn(repoUrl);
+      return;
+    }
+  }
 
   if (alreadyStarred) {
-    ok(`이미 함께하고 계시군요. ⭐`);
+    ok("이미 함께하고 계시군요. ⭐");
+    markPrompted();
     return;
   }
 
-  if (await confirm(`⭐ 하나가 큰 차이를 만듭니다.`, true)) {
-    try {
-      execFileSync("gh", ["api", "-X", "PUT", "/user/starred/{owner}/{repo}"], {
-        timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
-      });
-      ok(`함께해 주셔서 감사합니다. ⭐`);
-    } catch {
-      info(`https://github.com/{owner}/{repo}`);
-    }
+  let accepted = false;
+  if (useSoft) {
+    accepted = await confirm("⭐ 하나가 큰 차이를 만듭니다.", true);
   } else {
-    // 거절 시 URL만 조용히
-    console.log(`     https://github.com/{owner}/{repo}`);
+    const answer = await askUserQuestion({
+      question: "⭐ 이 프로젝트가 마음에 드셨나요? 스타를 누르시겠습니까?",
+      options: ["예, 누를게요", "아니오"],
+    });
+    accepted = answer === "예, 누를게요";
   }
-}
-```
 
-### 비인터랙티브 (postinstall / CLI banner)
-
-confirm 불가한 환경. 이미 스타 여부만 감지하고 메시지 분기.
+  if (!accepted) {
+    if (useSoft) {
+      info(repoUrl);
+    } else {
+      info(`괜찮습니다. 나중에 마음이 바뀌시면: ${repoUrl}`);
+    }
+    markPrompted();
+    return;
+  }
 
-```javascript
-try {
-  execFileSync("gh", ["auth", "status"], { timeout: 5000, stdio: ["pipe","pipe","pipe"] });
   try {
-    execFileSync("gh", ["api", "user/starred/{owner}/{repo}"], { timeout: 5000, stdio: ["pipe","pipe","pipe"] });
-    ok(`이미 함께하고 계시군요. ⭐`);
+    runGh(["api", "-X", "PUT", `/user/starred/${owner}/${repo}`]);
+    if (useSoft) {
+      ok("함께해 주셔서 감사합니다. ⭐");
+    } else {
+      ok("감사합니다! 여러분의 ⭐가 프로젝트를 성장시킵니다.");
+    }
   } catch {
-    info(`⭐ 하나가 큰 차이를 만듭니다. https://github.com/{owner}/{repo}`);
+    warn(repoUrl);
+  } finally {
+    markPrompted();
   }
-} catch {
-  info(`⭐ 하나가 큰 차이를 만듭니다. https://github.com/{owner}/{repo}`);
 }
 ```
 
 ## 적용 시 규칙
 
-1. `{owner}/{repo}`를 대상 리포로 치환한다
-2. 프로젝트의 기존 ANSI 컬러 상수(AMBER, CYAN, RESET 등)를 사용한다
-3. setup 완료 직후, 최종 요약 다음에 호출한다 — 핵심 설정 흐름을 방해하지 않는다
-4. 모든 gh 호출은 `timeout: 5000`, `stdio: ["pipe","pipe","pipe"]`로 감싸서 실패해도 setup을 블로킹하지 않는다
-5. 거절 시 죄책감을 주지 않는다 — URL만 조용히 남긴다
-
-## UX 카피 톤
-
-Apple 스타일: 짧고, 자신감 있고, 부담 없이.
-
-| 상황 | 멘트 |
-|------|------|
-| 이미 스타 | `이미 함께하고 계시군요. ⭐` |
-| 요청 | `⭐ 하나가 큰 차이를 만듭니다.` |
-| 수락 후 | `함께해 주셔서 감사합니다. ⭐` |
-| 거절 | URL만 |
-| gh 없음 | `⭐ 하나가 큰 차이를 만듭니다.` + URL |
+1. 기본 모드는 aggressive이며 `--soft` 전달 시에만 soft 모드로 전환한다.
+2. CI/비인터랙티브 감지는 아래 조건으로 강제 soft 폴백한다.
+   - `!process.stdout.isTTY || process.env.CI || process.env.TERM === "dumb"`
+3. gh 설치 확인은 `which` 대신 `gh --version`으로 수행한다 (크로스플랫폼).
+4. gh 인증 확인은 `gh auth status`로 수행한다.
+5. 스타 여부 체크는 `gh api user/starred/{owner}/{repo}`를 사용하고, `404`만 미스타로 판단한다.
+6. 스타 체크 API 에러가 `404` 외 상태면 프롬프트를 띄우지 않고 URL만 출력하며 마커를 남기지 않는다.
+7. 중복 요청 방지를 위해 아래 마커를 사용한다.
+   - `~/.config/star-prompt/{owner}-{repo}.prompted`
+   - 이미 스타한 유저도 `markPrompted()`를 호출한다.
+8. 모든 gh 호출은 `timeout: 10000`, `stdio: ["pipe","pipe","pipe"]`를 사용한다.
+9. setup/postinstall의 핵심 성공/실패 처리 흐름을 막지 않도록, 스타 로직 실패는 모두 조용히 폴백한다.
+
+## UX 카피 테이블
+
+| 상황 | Aggressive (기본) | Soft (`--soft`) |
+|------|-------------------|-----------------|
+| 이미 스타 | `이미 함께하고 계시군요. ⭐` | (동일) |
+| 요청 | `AskUserQuestion: ⭐ 이 프로젝트가 마음에 드셨나요? 스타를 누르시겠습니까?` | `⭐ 하나가 큰 차이를 만듭니다.` |
+| 수락 후 | `감사합니다! 여러분의 ⭐가 프로젝트를 성장시킵니다.` | `함께해 주셔서 감사합니다. ⭐` |
+| 거절 | `괜찮습니다. 나중에 마음이 바뀌시면:` + URL | URL만 |
+| gh 미설치 | URL만 표시 | (동일) |
+| gh 미인증 | URL만 표시 | (동일) |
+| CI/비인터랙티브 | soft 자동 폴백 | (동일) |
+| API 에러 (404 외) | 프롬프트 없이 URL만 표시, 마커 안 남김 | (동일) |
+| 이미 프롬프트 본 유저 | 스킵 | (동일) |