@elyun/bylane 1.18.0 → 1.19.0

package/README.md

@@ -69,6 +69,34 @@ node src/cli.js install
 
 인터랙티브 설정 (GitHub 접근 방법, 알림 채널, 브랜치 패턴, 에이전트 모델 등).
 
+### 사전 점검
+
+설정이 올바른지 확인하려면:
+
+```bash
+npx @elyun/bylane preflight
+```
+
+또는 Claude Code에서:
+
+```
+/bylane preflight
+```
+
+점검 항목: bylane.json 존재, GitHub CLI 로그인, GITHUB_TOKEN, Slack/Telegram 연동 설정.
+문제가 있으면 항목마다 수정 방법을 안내합니다.
+
+```
+── byLane 사전 점검 ──
+
+✓  bylane 설정              v1.0
+✓  GitHub CLI (fallback)   github.com
+!  GitHub Token (fallback)  GITHUB_TOKEN 환경변수 없음
+     → export GITHUB_TOKEN=ghp_xxxx
+```
+
+모든 에이전트 실행 전 자동으로 점검하여 연동 오류로 인한 중간 실패를 방지합니다.
+
 ---
 
 ## 사용법

package/commands/bylane-orchestrator.md

@@ -11,7 +11,13 @@ description: byLane 메인 오케스트레이터. 자연어 의도를 파싱해
 
 ## 실행 전 체크
 
-1. `.bylane/bylane.json` 로드. 없으면 즉시 `bylane-setup` 스킬 실행.
+1. 사전 점검 실행:
+   ```bash
+   npx @elyun/bylane preflight
+   ```
+   - 점검 실패 시 안내 메시지를 출력하고 워크플로우를 **중단**한다.
+   - `.bylane/bylane.json` 없으면 즉시 `bylane-setup` 스킬 실행.
+
 2. `.bylane/state/` 디렉토리 확인. 없으면 생성.
 
 ## 에이전트별 모델 결정

package/commands/bylane.md

@@ -25,6 +25,25 @@ description: byLane 메인 커맨드. 자연어로 전체 개발 워크플로우
 /bylane status         — 현재 상태 한 줄 요약
 ```
 
+## 사전 점검 (모든 명령 전 자동 실행)
+
+서브커맨드를 라우팅하기 전 아래 점검을 실행한다:
+
+```bash
+npx @elyun/bylane preflight
+```
+
+점검 항목:
+- `.bylane/bylane.json` 존재 여부 → 없으면 `/bylane setup` 안내 후 중단
+- GitHub 접근 방법 (`github.method` 기준):
+  - `cli`: `gh auth status` → 로그인 안 됐으면 `gh auth login` 안내
+  - `api`: `GITHUB_TOKEN` 환경변수 → 없으면 설정 방법 안내
+  - `auto`/`mcp`: CLI + Token 둘 다 확인, 어느 것도 없으면 안내
+- 알림 채널 (활성화된 경우만): Slack 채널 설정 여부, Telegram 토큰 여부
+
+문제가 있으면 각 항목마다 수정 방법을 출력하고 중단한다.
+`setup`, `status`, `preflight` 서브커맨드는 점검 없이 바로 실행한다.
+
 ## 실행 흐름
 
 첫 번째 인자가 서브커맨드인지 확인.
@@ -47,6 +66,7 @@ description: byLane 메인 커맨드. 자연어로 전체 개발 워크플로우
 | `respond-loop` | `bylane-respond-loop` |
 | `notify` | `bylane-notify-agent` |
 | `status` | `.bylane/state/` 파일 읽어 한 줄 요약 출력 |
+| `preflight` | 연동 상태 점검 및 문제 안내 |
 
 ## monitor 서브커맨드
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elyun/bylane",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Frontend development harness for Claude Code",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -141,6 +141,11 @@ function install() {
 
 if (command === 'install') {
   install()
+} else if (command === 'preflight') {
+  const { runPreflight, formatPreflight } = await import('./preflight.js')
+  const result = runPreflight()
+  console.log(formatPreflight(result))
+  if (!result.passed) process.exit(1)
 } else if (command === 'models') {
   // models → 에이전트별 모델 목록 출력 (KEY=VALUE 형식)
   const { loadConfig, getAgentModel } = await import('./config.js')

package/src/loop-utils.js

@@ -0,0 +1,47 @@
+/**
+ * loop-utils.js
+ * 루프 프로세스 공통 유틸
+ */
+import { execSync } from 'child_process'
+import { readState, writeState } from './state.js'
+
+/**
+ * 동일 루프가 이미 실행 중이면 기존 프로세스를 종료하고 기다린다.
+ * @param {string} loopName  e.g. 'review-loop'
+ * @param {string} stateDir
+ */
+export function killExistingLoop(loopName, stateDir = '.bylane/state') {
+  const existing = readState(loopName, stateDir)
+  if (!existing || existing.status !== 'running' || !existing.pid) return
+
+  const pid = Number(existing.pid)
+  if (pid === process.pid) return   // 자기 자신이면 무시
+
+  // PID가 살아있는지 확인
+  try {
+    process.kill(pid, 0)
+  } catch {
+    // 이미 종료된 프로세스 — 상태만 정리
+    writeState(loopName, { ...existing, status: 'stopped', stoppedAt: new Date().toISOString() }, stateDir)
+    return
+  }
+
+  // 기존 프로세스 종료
+  console.log(`[${loopName}] 기존 프로세스(PID: ${pid}) 종료 후 재시작합니다.`)
+  try {
+    process.kill(pid, 'SIGTERM')
+  } catch {
+    // 종료 실패 시 무시하고 계속
+  }
+
+  // 최대 2초 대기 (100ms 간격 폴링)
+  const deadline = Date.now() + 2000
+  while (Date.now() < deadline) {
+    try {
+      process.kill(pid, 0)
+      execSync('sleep 0.1')
+    } catch {
+      break  // 종료 완료
+    }
+  }
+}

package/src/preflight.js

@@ -0,0 +1,146 @@
+/**
+ * preflight.js
+ * GitHub CLI/MCP/API, 알림 채널 연동 상태를 점검하고 문제가 있으면 가이드를 출력한다.
+ * `npx @elyun/bylane preflight` 또는 에이전트 시작 전 자동 실행.
+ */
+import { execSync } from 'child_process'
+import { existsSync } from 'fs'
+import { loadConfig } from './config.js'
+
+const CONFIG_PATH = '.bylane/bylane.json'
+
+function run(cmd) {
+  try {
+    return { ok: true, out: execSync(cmd, { encoding: 'utf8', stdio: ['pipe','pipe','pipe'] }).trim() }
+  } catch (e) {
+    return { ok: false, out: e.stderr?.toString().trim() ?? '' }
+  }
+}
+
+function checkGhCli() {
+  const which = run('which gh')
+  if (!which.ok) return { ok: false, reason: 'gh CLI 미설치', fix: 'brew install gh  # 또는 https://cli.github.com' }
+
+  const auth = run('gh auth status')
+  if (!auth.ok) return { ok: false, reason: 'gh CLI 로그인 필요', fix: 'gh auth login' }
+
+  return { ok: true, detail: auth.out.split('\n')[0] }
+}
+
+function checkGithubToken() {
+  const token = process.env.GITHUB_TOKEN
+  if (!token) return { ok: false, reason: 'GITHUB_TOKEN 환경변수 없음', fix: 'export GITHUB_TOKEN=ghp_xxxx' }
+  if (token.length < 10) return { ok: false, reason: 'GITHUB_TOKEN 값이 너무 짧음', fix: '올바른 토큰을 설정하세요' }
+  return { ok: true, detail: `설정됨 (${token.slice(0,4)}…)` }
+}
+
+function checkSlack(config) {
+  if (!config.notifications?.slack?.enabled) return null
+  const channel = config.notifications.slack.channel
+  if (!channel) return { ok: false, reason: 'slack.channel 미설정', fix: '.bylane/bylane.json의 notifications.slack.channel 설정' }
+  return { ok: true, detail: `채널: ${channel}` }
+}
+
+function checkTelegram(config) {
+  if (!config.notifications?.telegram?.enabled) return null
+  const botToken = process.env.TELEGRAM_BOT_TOKEN
+  const chatId = process.env.TELEGRAM_CHAT_ID || config.notifications.telegram.chatId
+  if (!botToken) return { ok: false, reason: 'TELEGRAM_BOT_TOKEN 환경변수 없음', fix: 'export TELEGRAM_BOT_TOKEN=xxx' }
+  if (!chatId) return { ok: false, reason: 'TELEGRAM_CHAT_ID 미설정', fix: 'export TELEGRAM_CHAT_ID=xxx 또는 bylane.json에 설정' }
+  return { ok: true, detail: `chat_id: ${chatId}` }
+}
+
+/**
+ * 전체 점검 실행
+ * @returns {{ passed: boolean, results: Array<{name, ok, detail?, reason?, fix?}> }}
+ */
+export function runPreflight() {
+  const results = []
+
+  // 1. bylane.json 존재 여부
+  if (!existsSync(CONFIG_PATH)) {
+    results.push({
+      name: 'bylane 설정',
+      ok: false,
+      reason: '.bylane/bylane.json 없음',
+      fix: '/bylane setup  을 실행하여 초기 설정을 완료하세요.'
+    })
+    return { passed: false, results }
+  }
+
+  let config
+  try { config = loadConfig() } catch (e) {
+    results.push({ name: 'bylane 설정', ok: false, reason: `bylane.json 파싱 오류: ${e.message}`, fix: '/bylane setup 으로 재생성' })
+    return { passed: false, results }
+  }
+  results.push({ name: 'bylane 설정', ok: true, detail: `v${config.version ?? '?'}` })
+
+  // 2. GitHub 접근
+  const method = config.github?.method ?? 'auto'
+
+  if (method === 'cli') {
+    const r = checkGhCli()
+    results.push({ name: 'GitHub CLI', ...r })
+  } else if (method === 'api') {
+    const r = checkGithubToken()
+    results.push({ name: 'GitHub Token', ...r })
+  } else if (method === 'auto' || method === 'mcp') {
+    // auto/mcp: CLI도 확인해두면 유용
+    const cli = checkGhCli()
+    const token = checkGithubToken()
+    const anyOk = cli.ok || token.ok
+
+    if (method === 'mcp') {
+      results.push({
+        name: 'GitHub MCP',
+        ok: true,
+        detail: 'Claude Code 세션에서 자동 사용 (별도 확인 불필요)'
+      })
+    }
+    results.push({ name: 'GitHub CLI (fallback)', ...cli })
+    results.push({ name: 'GitHub Token (fallback)', ...token })
+
+    if (!anyOk && method === 'auto') {
+      results.find(r => r.name === 'GitHub CLI (fallback)').critical = true
+    }
+  }
+
+  // 3. 알림 채널 (설정된 경우만)
+  const slack = checkSlack(config)
+  if (slack) results.push({ name: 'Slack 알림', ...slack })
+
+  const telegram = checkTelegram(config)
+  if (telegram) results.push({ name: 'Telegram 알림', ...telegram })
+
+  const passed = results.every(r => r.ok)
+  return { passed, results }
+}
+
+/** 결과를 읽기 좋은 텍스트로 포맷 */
+export function formatPreflight({ passed, results }) {
+  const lines = []
+  lines.push('')
+  lines.push('  ── byLane 사전 점검 ──')
+  lines.push('')
+
+  for (const r of results) {
+    const icon = r.ok ? '  ✓' : (r.critical ? '  ✗' : '  !')
+    const name = r.name.padEnd(22)
+    const desc = r.ok ? (r.detail ?? 'OK') : r.reason
+    lines.push(`${icon}  ${name} ${desc}`)
+    if (!r.ok && r.fix) {
+      lines.push(`       → ${r.fix}`)
+    }
+  }
+
+  lines.push('')
+  if (passed) {
+    lines.push('  모든 항목 정상. 워크플로우를 시작합니다.')
+  } else {
+    lines.push('  일부 항목에 문제가 있습니다. 위 안내를 참고하여 설정을 완료하세요.')
+    lines.push('  설정 완료 후 명령을 다시 실행하거나 /bylane setup 을 실행하세요.')
+  }
+  lines.push('')
+
+  return lines.join('\n')
+}

package/src/respond-loop.js

@@ -8,11 +8,13 @@ import { execSync } from 'child_process'
 import { mkdirSync } from 'fs'
 import { writeState, readState, appendLog } from './state.js'
 import { loadConfig } from './config.js'
+import { killExistingLoop } from './loop-utils.js'
 
 const INTERVAL_MS = 5 * 60 * 1000
 const STATE_DIR = '.bylane/state'
 
 mkdirSync(STATE_DIR, { recursive: true })
+killExistingLoop('respond-loop', STATE_DIR)
 
 function fetchMyPRsWithReviews(method, owner, repo) {
   // CLI

package/src/review-loop.js

@@ -7,11 +7,13 @@ import { execSync } from 'child_process'
 import { mkdirSync } from 'fs'
 import { writeState, readState, appendLog } from './state.js'
 import { loadConfig } from './config.js'
+import { killExistingLoop } from './loop-utils.js'
 
 const INTERVAL_MS = 5 * 60 * 1000
 const STATE_DIR = '.bylane/state'
 
 mkdirSync(STATE_DIR, { recursive: true })
+killExistingLoop('review-loop', STATE_DIR)
 
 function fetchPendingReviews(method, owner, repo) {
   // CLI