@elyun/bylane 1.17.0 → 1.19.0

package/commands/bylane-notify-agent.md

@@ -14,7 +14,7 @@ description: 워크플로우 완료 또는 개입 필요 시 Slack/Telegram으
 ## 실행 전 상태 기록
 
 ```bash
-node -e "import('./src/state.js').then(({writeState})=>writeState('notify-agent',{status:'in_progress',startedAt:new Date().toISOString(),progress:0,retries:0,log:[]}))"
+npx @elyun/bylane state write notify-agent '{"status":"in_progress","startedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","progress":0,"retries":0,"log":[]}'
 ```
 
 ## 실행 흐름

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/` 디렉토리 확인. 없으면 생성.
 
 ## 에이전트별 모델 결정
@@ -19,19 +25,11 @@ description: byLane 메인 오케스트레이터. 자연어 의도를 파싱해
 각 에이전트 실행 전 사용할 모델을 config에서 읽는다:
 
 ```bash
-node -e "
-import('./src/config.js').then(({loadConfig, getAgentModel}) => {
-  const config = loadConfig()
-  const agents = [
-    'orchestrator','issue-agent','code-agent','test-agent',
-    'commit-agent','pr-agent','review-agent','respond-agent','notify-agent'
-  ]
-  agents.forEach(a => console.log(a + ': ' + getAgentModel(config, a)))
-  // analyze-agent는 항상 opus 사용 (config 무관)
-})
-"
+npx @elyun/bylane models
 ```
 
+출력 형식: `AGENT_NAME=MODEL_ID` (한 줄씩)
+
 에이전트 호출 시 해당 모델을 `model` 파라미터로 전달한다.
 
 ## 의도 파싱 규칙
@@ -57,18 +55,7 @@ import('./src/config.js').then(({loadConfig, getAgentModel}) => {
 
 상태 기록 (각 에이전트 시작 전):
 ```bash
-node -e "
-import('./src/state.js').then(({writeState}) => {
-  writeState('AGENT_NAME', {
-    status: 'in_progress',
-    startedAt: new Date().toISOString(),
-    progress: 0,
-    currentTask: 'TASK_DESCRIPTION',
-    retries: 0,
-    log: []
-  })
-})
-"
+npx @elyun/bylane state write AGENT_NAME '{"status":"in_progress","startedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","progress":0,"currentTask":"TASK_DESCRIPTION","retries":0,"log":[]}'
 ```
 
 ## 피드백 루프

package/commands/bylane-pr-agent.md

@@ -43,7 +43,7 @@ ls .github/PULL_REQUEST_TEMPLATE/*.md 2>/dev/null | head -5
 ## 실행 전 상태 기록
 
 ```bash
-node -e "import('./src/state.js').then(({writeState})=>writeState('pr-agent',{status:'in_progress',startedAt:new Date().toISOString(),progress:0,retries:0,log:[]}))"
+npx @elyun/bylane state write pr-agent '{"status":"in_progress","startedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","progress":0,"retries":0,"log":[]}'
 ```
 
 ## 실행 흐름
@@ -90,7 +90,7 @@ node -e "import('./src/state.js').then(({writeState})=>writeState('pr-agent',{st
 
 4. 상태 업데이트:
    ```bash
-   node -e "import('./src/state.js').then(({writeState})=>writeState('pr-agent',{status:'completed',progress:100,prNumber:PR_NUMBER,prUrl:'PR_URL'}))"
+   npx @elyun/bylane state write pr-agent '{"status":"completed","progress":100,"prNumber":PR_NUMBER,"prUrl":"PR_URL"}'
    ```
 
 ## 출력

package/commands/bylane-respond-agent.md

@@ -64,7 +64,7 @@ ls .github/REVIEW_RESPONSE_TEMPLATE.md \
 ## 실행 전 상태 기록
 
 ```bash
-node -e "import('./src/state.js').then(({writeState})=>writeState('respond-agent',{status:'in_progress',startedAt:new Date().toISOString(),progress:0,retries:0,log:[]}))"
+npx @elyun/bylane state write respond-agent '{"status":"in_progress","startedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","progress":0,"retries":0,"log":[]}'
 ```
 
 ## 실행 흐름

package/commands/bylane-respond-loop.md

@@ -30,15 +30,12 @@ echo "폴러 PID: $!"
 pending PR이 생길 때마다 respond-agent를 실행한다:
 
 ```bash
-node -e "
-import('./src/state.js').then(({readState}) => {
-  const q = readState('respond-queue', '.bylane/state')
-  const pending = (q?.queue ?? []).filter(p => p.status === 'pending')
-  console.log(JSON.stringify(pending))
-})
-"
+# 큐 확인 (pending 항목 필터링)
+npx @elyun/bylane state read respond-queue
 ```
 
+출력된 JSON에서 `queue` 배열의 `status === "pending"` 항목을 선택한다.
+
 pending 항목이 있으면 각 PR에 대해:
 
 1. `hasChangesRequested` 여부 확인:
@@ -50,17 +47,8 @@ pending 항목이 있으면 각 PR에 대해:
 3. 완료 후 큐 항목을 `status: "responded"`로 업데이트:
 
 ```bash
-node -e "
-import('./src/state.js').then(({readState, writeState}) => {
-  const q = readState('respond-queue', '.bylane/state')
-  const queue = (q?.queue ?? []).map(p =>
-    p.number === PR_NUMBER
-      ? { ...p, status: 'responded', respondedAt: new Date().toISOString() }
-      : p
-  )
-  writeState('respond-queue', { status: 'running', queue }, '.bylane/state')
-})
-"
+# 현재 큐 읽기 후 PR_NUMBER 항목을 responded로 업데이트하여 다시 쓰기
+npx @elyun/bylane state write respond-queue '{"status":"running","queue":UPDATED_QUEUE_JSON}'
 ```
 
 4. 다음 pending 항목으로 반복. pending 없으면 5분 대기 후 재확인 (폴러 주기와 동일).

package/commands/bylane-review-agent.md

@@ -69,7 +69,7 @@ Enter 또는 아무것도 선택하지 않으면 → `all` (전체 검사)
 ## 실행 전 상태 기록
 
 ```bash
-node -e "import('./src/state.js').then(({writeState})=>writeState('review-agent',{status:'in_progress',startedAt:new Date().toISOString(),progress:0,retries:0,log:[]}))"
+npx @elyun/bylane state write review-agent '{"status":"in_progress","startedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","progress":0,"retries":0,"log":[]}'
 ```
 
 ## 실행 흐름
@@ -180,7 +180,7 @@ curl -s -X POST \
 ### 5. 상태 업데이트
 
 ```bash
-node -e "import('./src/state.js').then(({writeState})=>writeState('review-agent',{status:'completed',progress:100,approved:APPROVED_BOOL,commentCount:COMMENT_COUNT}))"
+npx @elyun/bylane state write review-agent '{"status":"completed","progress":100,"approved":APPROVED_BOOL,"commentCount":COMMENT_COUNT}'
 ```
 
 ## 출력

package/commands/bylane-review-loop.md

@@ -47,30 +47,19 @@ node src/review-loop.js
 아래 루프를 실행하면서 pending PR이 생길 때마다 review-agent를 실행한다:
 
 ```bash
-# 큐 확인
-node -e "
-import('./src/state.js').then(({readState}) => {
-  const q = readState('review-queue', '.bylane/state')
-  const pending = (q?.queue ?? []).filter(p => p.status === 'pending')
-  console.log(JSON.stringify(pending))
-})
-"
+# 큐 확인 (pending 항목 필터링)
+npx @elyun/bylane state read review-queue
 ```
 
+출력된 JSON에서 `queue` 배열의 `status === "pending"` 항목을 선택한다.
+
 pending 항목이 있으면 각 PR에 대해:
 1. `bylane-review-agent` skill 실행 (PR 번호 전달)
 2. 리뷰 완료 후 큐 항목을 `status: "reviewed"`로 업데이트:
 
 ```bash
-node -e "
-import('./src/state.js').then(({readState, writeState}) => {
-  const q = readState('review-queue', '.bylane/state')
-  const queue = (q?.queue ?? []).map(p =>
-    p.number === PR_NUMBER ? { ...p, status: 'reviewed', reviewedAt: new Date().toISOString() } : p
-  )
-  writeState('review-queue', { status: 'running', queue }, '.bylane/state')
-})
-"
+# 현재 큐 읽기 후 PR_NUMBER 항목을 reviewed로 업데이트하여 다시 쓰기
+npx @elyun/bylane state write review-queue '{"status":"running","queue":UPDATED_QUEUE_JSON}'
 ```
 
 3. 다음 pending 항목으로 반복

package/commands/bylane-test-agent.md

@@ -12,7 +12,7 @@ description: 변경된 코드의 테스트를 실행하고 결과를 반환한
 ## 실행 전 상태 기록
 
 ```bash
-node -e "import('./src/state.js').then(({writeState})=>writeState('test-agent',{status:'in_progress',startedAt:new Date().toISOString(),progress:0,retries:0,log:[]}))"
+npx @elyun/bylane state write test-agent '{"status":"in_progress","startedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","progress":0,"retries":0,"log":[]}'
 ```
 
 ## 실행 흐름

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.17.0",
+  "version": "1.19.0",
   "description": "Frontend development harness for Claude Code",
   "type": "module",
   "bin": {

package/src/cleanup.js

@@ -0,0 +1,152 @@
+/**
+ * cleanup.js
+ * 상태 파일 정리, 권한 수정, 좀비 프로세스/에이전트 초기화
+ * monitor [r] 키 또는 `npx @elyun/bylane cleanup`으로 실행
+ */
+import { readdirSync, chmodSync, existsSync, unlinkSync, readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { join } from 'path'
+import { readState, writeState } from './state.js'
+
+const STATE_DIR = '.bylane/state'
+const STALE_MS = 30 * 60 * 1000   // 30분 이상 in_progress → 초기화
+const SUBAGENTS_FILE = join(STATE_DIR, 'subagents.json')
+
+/** 프로세스가 살아있는지 확인 (kill -0) */
+function isPidAlive(pid) {
+  try {
+    process.kill(Number(pid), 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** subagents.json에서 죽은 PID 제거 */
+function cleanSubagents() {
+  if (!existsSync(SUBAGENTS_FILE)) return []
+  let data
+  try { data = JSON.parse(readFileSync(SUBAGENTS_FILE, 'utf8')) } catch { return [] }
+
+  const before = (data.active ?? []).length
+  const active = (data.active ?? []).filter(a => {
+    if (!a.pid) return false
+    return isPidAlive(a.pid)
+  })
+  const cleaned = before - active.length
+
+  if (cleaned > 0) {
+    writeFileSync(SUBAGENTS_FILE, JSON.stringify({ ...data, active }, null, 2))
+  }
+  return cleaned > 0 ? [`subagents.json: active ${before}개 → ${active.length}개 (${cleaned}개 제거)`] : []
+}
+
+/** 디렉토리 및 파일 권한 수정 */
+function fixPermissions() {
+  const fixed = []
+  try {
+    chmodSync(STATE_DIR, 0o755)
+  } catch {}
+
+  const files = existsSync(STATE_DIR)
+    ? readdirSync(STATE_DIR).filter(f => f.endsWith('.json'))
+    : []
+
+  for (const file of files) {
+    try {
+      chmodSync(join(STATE_DIR, file), 0o644)
+    } catch (e) {
+      fixed.push(`권한 수정 실패: ${file} — ${e.message}`)
+    }
+  }
+  return fixed
+}
+
+/**
+ * 전체 정리 실행
+ * @returns {{ fixed: string[], killed: string[], reset: string[], cleared: string[] }}
+ */
+export function runCleanup() {
+  const result = { fixed: [], killed: [], reset: [], cleared: [] }
+
+  if (!existsSync(STATE_DIR)) {
+    mkdirSync(STATE_DIR, { recursive: true })
+    return result
+  }
+
+  // 1. 파일 권한 수정
+  result.fixed.push(...fixPermissions())
+
+  // 2. 상태 파일 순회
+  const files = readdirSync(STATE_DIR).filter(f => f.endsWith('.json'))
+
+  for (const file of files) {
+    const name = file.replace('.json', '')
+
+    // 특수 파일 건너뜀
+    if (name === 'cancel') continue
+
+    // subagents 별도 처리
+    if (name === 'subagents') {
+      result.cleared.push(...cleanSubagents())
+      continue
+    }
+
+    const state = readState(name, STATE_DIR)
+    if (!state) continue
+
+    // 루프: PID가 죽었으면 stopped로 전환
+    if (name.endsWith('-loop') && state.pid && state.status === 'running') {
+      if (!isPidAlive(state.pid)) {
+        writeState(name, { ...state, status: 'stopped', stoppedAt: new Date().toISOString() }, STATE_DIR)
+        result.killed.push(`${name}: PID ${state.pid} 없음 → stopped`)
+      }
+    }
+
+    // in_progress 상태가 30분 이상 → failed로 초기화
+    if (state.status === 'in_progress' && state.startedAt) {
+      const age = Date.now() - new Date(state.startedAt).getTime()
+      if (age > STALE_MS) {
+        writeState(name, {
+          ...state,
+          status: 'failed',
+          error: `stale: ${Math.floor(age / 60000)}분 초과 in_progress`
+        }, STATE_DIR)
+        result.reset.push(`${name}: ${Math.floor(age / 60000)}분 in_progress → failed`)
+      }
+    }
+
+    // 큐 파일: responding/reviewing 상태가 남아있으면 pending으로 복구
+    if ((name === 'review-queue' || name === 'respond-queue') && Array.isArray(state.queue)) {
+      const fixed = state.queue.map(item =>
+        item.status === 'reviewing' || item.status === 'responding'
+          ? { ...item, status: 'pending', recoveredAt: new Date().toISOString() }
+          : item
+      )
+      const changedCount = fixed.filter((item, i) => item.status !== state.queue[i].status).length
+      if (changedCount > 0) {
+        writeState(name, { ...state, queue: fixed }, STATE_DIR)
+        result.reset.push(`${name}: ${changedCount}개 진행중 항목 → pending 복구`)
+      }
+    }
+  }
+
+  return result
+}
+
+/** 결과를 사람이 읽기 쉬운 문자열로 출력 */
+export function formatCleanupResult(result) {
+  const lines = []
+  const total = Object.values(result).reduce((s, arr) => s + arr.length, 0)
+
+  if (total === 0) {
+    lines.push('정리할 항목 없음.')
+    return lines.join('\n')
+  }
+
+  if (result.killed.length)  lines.push('  [종료]', ...result.killed.map(s => `    · ${s}`))
+  if (result.reset.length)   lines.push('  [초기화]', ...result.reset.map(s => `    · ${s}`))
+  if (result.cleared.length) lines.push('  [정리]', ...result.cleared.map(s => `    · ${s}`))
+  if (result.fixed.length)   lines.push('  [오류]', ...result.fixed.map(s => `    · ${s}`))
+
+  return lines.join('\n')
+}

package/src/cli.js

@@ -141,6 +141,50 @@ 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')
+  const config = loadConfig()
+  const agents = ['orchestrator','issue-agent','code-agent','test-agent',
+    'commit-agent','pr-agent','review-agent','respond-agent','notify-agent','analyze-agent']
+  agents.forEach(a => console.log(`${a}=${getAgentModel(config, a)}`))
+} else if (command === 'branch') {
+  // branch ISSUE_NUMBER  → 브랜치명 출력
+  const issueNumber = Number(args[1])
+  if (!issueNumber) { console.error('사용법: bylane branch <issueNumber>'); process.exit(1) }
+  const { buildBranchNameFromConfig } = await import('./branch.js')
+  const { loadConfig } = await import('./config.js')
+  console.log(buildBranchNameFromConfig(loadConfig(), issueNumber))
+} else if (command === 'state') {
+  // state write AGENT '{"status":"in_progress",...}'
+  // state append AGENT "메시지"
+  // state read AGENT
+  const subCmd = args[1]
+  const agentName = args[2]
+  const payload = args[3]
+  const { writeState, appendLog, readState } = await import('./state.js')
+
+  if (subCmd === 'write' && agentName && payload) {
+    writeState(agentName, JSON.parse(payload))
+  } else if (subCmd === 'append' && agentName && payload) {
+    appendLog(agentName, payload)
+  } else if (subCmd === 'read' && agentName) {
+    console.log(JSON.stringify(readState(agentName), null, 2))
+  } else {
+    console.error('사용법: bylane state <write|append|read> <agentName> [payload]')
+    process.exit(1)
+  }
+} else if (command === 'cleanup') {
+  const { runCleanup, formatCleanupResult } = await import('./cleanup.js')
+  console.log('\n  byLane 상태 정리 중...\n')
+  const result = runCleanup()
+  console.log(formatCleanupResult(result))
+  console.log('\n  완료.\n')
 } else if (command === 'monitor') {
   // 항상 현재 패키지의 모니터 실행 (버전 일치 보장)
   const monitorPath = join(__dirname, 'monitor', 'index.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/monitor/index.js

@@ -4,6 +4,7 @@ import { createLayout } from './layout.js'
 import { createPoller } from './poller.js'
 import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'fs'
 import { join } from 'path'
+import { runCleanup, formatCleanupResult } from '../cleanup.js'
 
 const { screen, header, pipeline, log, queue, status, onCleanup } = createLayout()
 const poller = createPoller()
@@ -101,6 +102,34 @@ screen.key('s', () => {
   })
 })
 
+// 'r' — 상태 정리 (권한 수정, 좀비 초기화, 큐 복구)
+screen.key('r', () => {
+  header.update({
+    workflowTitle: '상태 정리 중...',
+    time: new Date().toLocaleTimeString('ko-KR', { hour12: false }),
+    elapsed: `${Math.floor((Date.now() - startTime) / 1000)}s`
+  })
+  screen.render()
+
+  try {
+    const result = runCleanup()
+    const summary = formatCleanupResult(result)
+    const total = Object.values(result).reduce((s, a) => s + a.length, 0)
+    header.update({
+      workflowTitle: total > 0 ? `정리 완료 (${total}건)` : '정리 완료 — 이상 없음',
+      time: new Date().toLocaleTimeString('ko-KR', { hour12: false }),
+      elapsed: `${Math.floor((Date.now() - startTime) / 1000)}s`
+    })
+  } catch (e) {
+    header.update({
+      workflowTitle: `정리 실패: ${e.message}`,
+      time: new Date().toLocaleTimeString('ko-KR', { hour12: false }),
+      elapsed: `${Math.floor((Date.now() - startTime) / 1000)}s`
+    })
+  }
+  screen.render()
+})
+
 // 'c' — 하위 에이전트 취소 플래그 토글
 screen.key('c', () => {
   if (existsSync(CANCEL_FILE)) {

package/src/monitor/layout.js

@@ -62,7 +62,7 @@ export function createLayout() {
     left: 0,
     width: '100%',
     height: 1,
-    content: ' [q]종료  [c]에이전트취소토글  [s]루프종료  [Tab]포커스  [j/k]로그스크롤',
+    content: ' [q]종료  [r]상태정리  [c]에이전트취소토글  [s]루프종료  [Tab]포커스  [j/k]로그스크롤',
     style: { fg: 'black', bg: 'cyan' }
   })
   screen.append(footer)