e2e-agent-runner 1.0.2 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # e2e-runner — suseona 작업 에이전트 로컬 러너
 
-내 컴퓨터의 **Claude Code** 로 `구현 → 테스트 → 리뷰 → 배포` 파이프라인을 자동 수행하는
+내 컴퓨터의 **Claude Code** 로 `구현 → 테스트 → 리뷰 → 배포` 파이프라인과 웹사이트 기능 지도 추출을 자동 수행하는
 상주 데몬입니다. 코드는 내 폴더에, 실행은 내 Claude 구독으로 — 서버(e2e)는 오케스트레이션만
 담당합니다. 아웃바운드 폴링만 쓰므로 인바운드 포트·포트포워딩이 필요 없습니다.
 
@@ -89,6 +89,20 @@ WantedBy=default.target
 | `CLAUDE_BIN` | | `claude` | claude CLI 경로(비표준 설치 위치) |
 | `POLL_S` / `HEARTBEAT_S` | | 3 / 30 | 폴링·하트비트 주기 |
 | `RUNNER_STEP_TIMEOUT_S` | | 2700 | 단계 타임아웃(서버 watchdog 3600s 보다 작게) |
+| `DISCOVER_TIMEOUT_S` / `MAX_TURNS_DISCOVER` | | 5400 / 500 | 기능 지도 추출 시간·턴 상한 |
+| `E2E_BROWSER_MCP` | | (Playwright) | `off`=브라우저 없이 코드만 / MCP 설정 JSON 경로=사용자 지정 브라우저 MCP |
+| `E2E_PLAYWRIGHT_MCP` | | `@playwright/mcp@0.0.84` | 기능 지도용 Playwright MCP 패키지 스펙 |
+| `E2E_BROWSER_HEADED` | | — | `1`이면 브라우저 창을 띄워 탐색(디버깅) |
+
+## 기능 지도 추출(웹사이트 프로젝트)
+
+웹에서 프로젝트 유형을 **웹사이트**로 지정하면 "기능 지도 추출"을 실행할 수 있습니다. 러너는
+Claude Code 에 **Playwright MCP**(`npx @playwright/mcp`, 격리 프로필·헤드리스)를 붙여 실행하고,
+Claude 는 소스의 라우트 정의를 읽은 뒤 **라이브 사이트에 직접 접속해 화면을 보며** 라우트별 기능과
+상세 정의(흐름·입력 검증·기대 결과·상태·예외·QA 체크포인트)를 임시 폴더에 기록합니다. 러너가 이를
+수집해 서버에 보고합니다. 이 단계는 **읽기 전용**(브랜치·커밋 없음)이며 라이브 사이트에서 삭제·결제·
+발송 같은 파괴적 동작을 하지 않도록 지시됩니다. 첫 실행 시 브라우저 다운로드가 필요할 수 있습니다
+(Claude 가 `browser_install` 로 자동 설치).
 
 ## 보안 노트
 

package/claude.mjs

@@ -44,11 +44,13 @@ const BRIEF_MAX = 240;   // tool_use 요약 상한
  * @param {(ev:{kind:string,data:object})=>void} opts.onEvent   message/tool 이벤트 콜백
  * @param {()=>boolean} opts.shouldCancel  취소 플래그 폴링(라인 수신·1s 인터벌)
  * @param {(sessionId:string)=>void} opts.onSessionId  init 이벤트 수신(session 저장·task_meta 전송)
+ * @param {string[]} [opts.extraArgs]  claude 추가 인자(discover 의 MCP·추가 디렉터리)
  * @returns {Promise<{ok:boolean, cancelled?:boolean, timedOut?:boolean, finalText?:string,
  *                     sessionId?:string|null, usage?:object|null, error?:string|null}>}
  */
 export function runClaude(opts) {
   const { cwd, prompt, resumeSessionId, maxTurns, timeoutS, onEvent, shouldCancel, onSessionId } = opts;
+  const extraArgs = opts.extraArgs ?? [];
   return new Promise((resolve) => {
     const args = [
       '-p', prompt,
@@ -57,11 +59,15 @@ export function runClaude(opts) {
       '--permission-mode', 'bypassPermissions',
       '--max-turns', String(maxTurns),
       ...(resumeSessionId ? ['--resume', resumeSessionId] : []),
+      // 페이즈별 추가 플래그(discover: --mcp-config 브라우저 MCP·--add-dir 산출 폴더).
+      // 가변 인자 플래그(--mcp-config/--add-dir)가 프롬프트를 삼키지 않도록 항상 마지막에 둔다.
+      ...extraArgs,
     ];
     // detached(POSIX)=신규 프로세스 그룹 — 취소·타임아웃이 claude 가 띄운 도구 자식(bash 등)까지
     // 종료시킨다. detached 로 파이프(stdio)는 그대로 동작한다.
+    // stdin 은 닫는다 — 파이프로 열려 있으면 claude -p 가 입력을 3s 기다린 뒤 경고하고 진행한다.
     const child = spawn(CLAUDE_BIN, args, {
-      cwd, env: process.env, detached: process.platform !== 'win32',
+      cwd, env: process.env, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'],
     });
     let settled = false;
     let cancelled = false;

package/discover.mjs

@@ -0,0 +1,221 @@
+// 기능 지도(Feature Map) 추출 — discover 페이즈 실행기.
+//
+// Claude Code 를 프로젝트 폴더(소스 코드 정찰)에서 실행하되, 브라우저 MCP(Playwright)를 붙여
+// 라이브 사이트에 직접 접속해 화면(스크린샷·접근성 스냅샷)을 보며 기능을 확인하게 한다.
+// Claude 는 러너가 만든 임시 산출 폴더에 라우트별 JSON(routes/NNN.json)과 map.json 을
+// 점진적으로 기록하고, 러너는 종료 후(시간 초과·실패 포함) 기록분을 수집해 artifact 로 보고한다.
+//
+// 읽기 전용 페이즈: git 브랜치·프리플라이트·커밋 없음. 저장소가 수정되면 경고 이벤트만 남긴다
+// (변경을 되돌리지 않는다 — 사용자 파일일 수 있으므로 판단은 사용자에게).
+//
+// env:
+//   E2E_BROWSER_MCP        off=브라우저 없이(코드만) | <JSON 파일 경로>=사용자 MCP 설정 | 미설정=Playwright MCP
+//   E2E_PLAYWRIGHT_MCP     Playwright MCP 패키지 스펙(기본 @playwright/mcp@0.0.84 — 고정 버전)
+//   E2E_BROWSER_HEADED=1   브라우저 창 표시(디버깅)
+//   E2E_KEEP_FM_OUT=1      산출 폴더 보존(디버깅)
+import { mkdtempSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+
+const PLAYWRIGHT_MCP = process.env.E2E_PLAYWRIGHT_MCP || '@playwright/mcp@0.0.84';
+const ARTIFACT_MAX_BYTES = 6 * 1024 * 1024; // step_result 본문 상한(서버가 다시 정규화·절단)
+const ROUTE_FILE_MAX_BYTES = 1024 * 1024;
+
+/** 산출 폴더 준비 + 브라우저 MCP 설정 → { outDir, routesDir, resultsDir, extraArgs, browser, promptAddon, cleanup }
+ *  results=true(QA 페이즈)면 results/ 폴더도 만들고 산출 안내에 포함한다. */
+export function prepareDiscover({ siteUrl, results = false }) {
+  const outDir = mkdtempSync(join(tmpdir(), 'e2e-fm-'));
+  const routesDir = join(outDir, 'routes');
+  const resultsDir = join(outDir, 'results');
+  const shotsDir = join(outDir, 'shots');
+  mkdirSync(routesDir, { recursive: true });
+  mkdirSync(shotsDir, { recursive: true });
+  if (results) mkdirSync(resultsDir, { recursive: true });
+
+  const mode = (process.env.E2E_BROWSER_MCP || '').trim();
+  let mcpPath = null;
+  let browser = 'playwright';
+  if (mode === 'off') {
+    browser = 'off';
+  } else if (mode && existsSync(mode)) {
+    mcpPath = mode; // 사용자 제공 MCP 설정(예: 사내 프록시·기존 Chrome 프로필)
+    browser = 'custom';
+  } else {
+    const pwArgs = [
+      '-y', PLAYWRIGHT_MCP,
+      '--isolated', // 매 실행 깨끗한 프로필 — 사용자 브라우저 세션·쿠키와 격리
+      '--viewport-size', '1440,900',
+      '--output-dir', shotsDir,
+      ...(process.env.E2E_BROWSER_HEADED === '1' ? [] : ['--headless']),
+    ];
+    // MCP 서버의 cwd 를 스크린샷 폴더로 고정 — Playwright MCP 는 상대 filename 을 자기 cwd(=claude cwd=
+    // 사용자 저장소) 기준으로 저장해 읽기 전용 탐색이 저장소를 오염시킨다(실검증에서 발견). mcp 설정엔
+    // cwd 필드가 없으므로 셸 래퍼로 이동 후 exec 한다(경로는 위치 인자로 전달 — 따옴표 주입 없음).
+    const server = process.platform === 'win32'
+      ? { command: 'cmd', args: ['/c', `cd /d "${shotsDir}" && npx ${pwArgs.map((a) => `"${a}"`).join(' ')}`] }
+      : { command: 'sh', args: ['-c', 'cd "$0" && exec npx "$@"', shotsDir, ...pwArgs] };
+    mcpPath = join(outDir, 'mcp.json');
+    writeFileSync(mcpPath, JSON.stringify({ mcpServers: { playwright: server } }, null, 2));
+  }
+
+  const extraArgs = ['--add-dir', outDir];
+  if (mcpPath) extraArgs.unshift('--mcp-config', mcpPath);
+
+  const promptAddon = [
+    '',
+    '# 산출물 위치(러너 지정 — 이 경로에만 쓰기)',
+    `- 라우트 파일 폴더: \`${routesDir}\`  (예: ${join(routesDir, '001.json')})`,
+    `- 서비스 요약 파일: \`${join(outDir, 'map.json')}\``,
+    ...(results ? [
+      `- QA 결과 파일 폴더: \`${resultsDir}\`  (예: ${join(resultsDir, '001-<id8>.json')})`,
+      `- 추가 산출 파일(QA 계획·재검증 페이즈): \`${join(outDir, 'plan.json')}\` · \`${join(outDir, 'retest.json')}\``,
+    ] : []),
+    `- 스크린샷 등 브라우저 산출물은 \`${shotsDir}\` 에 저장됩니다(저장소에 저장 금지).`,
+    '',
+    '# 브라우저 도구',
+    browser === 'off'
+      ? '- 이 머신은 브라우저 도구가 비활성화되어 있습니다(E2E_BROWSER_MCP=off). 코드 기반으로 추출하고 coverage.browser 를 "unavailable" 로 기록하세요.'
+      : [
+        `- 브라우저 MCP 도구(mcp__playwright__browser_* 등)를 사용해 ${siteUrl || '대상 사이트'} 에 직접 접속하세요.`,
+        '  browser_navigate 로 이동 → browser_take_screenshot 으로 화면을 직접 보고 → browser_snapshot 으로 요소를 확인 →',
+        '  browser_click/browser_type 등으로 비파괴적 상호작용을 확인합니다. 화면 폭 확인은 browser_resize.',
+        `- browser_take_screenshot 의 filename 을 지정할 때는 반드시 절대 경로(${shotsDir} 아래)를 쓰거나 생략하세요 — 저장소 폴더에 이미지를 저장하면 안 됩니다.`,
+        '- 브라우저 실행 파일이 없다는 오류가 나면 browser_install 도구를 한 번 실행한 뒤 다시 시도하세요.',
+        '- 브라우저 도구가 끝내 동작하지 않으면 코드 기반으로 계속하고 coverage.browser 를 "unavailable" 로 기록하세요.',
+      ].join('\n'),
+  ].join('\n');
+
+  const cleanup = () => {
+    if (process.env.E2E_KEEP_FM_OUT === '1') return;
+    try {
+      rmSync(outDir, { recursive: true, force: true });
+    } catch {
+      /* 임시 폴더 — OS 가 정리 */
+    }
+  };
+
+  return { outDir, routesDir, resultsDir, extraArgs, browser, promptAddon, cleanup };
+}
+
+/** 기록된 라우트 파일 수(진행률 이벤트용). */
+export function countRouteFiles(routesDir) {
+  try {
+    return readdirSync(routesDir).filter((f) => f.endsWith('.json')).length;
+  } catch {
+    return 0;
+  }
+}
+
+function readJson(path, maxBytes) {
+  const size = statSync(path).size;
+  if (size > maxBytes) throw new Error(`파일 과대(${size}B)`);
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+/** 최종 보고 텍스트의 마지막 ```json 블록 — 파일 기록이 전혀 없을 때의 폴백. */
+function fallbackFromText(text) {
+  if (!text) return null;
+  const blocks = [...text.matchAll(/```json\s*([\s\S]*?)```/g)];
+  for (let i = blocks.length - 1; i >= 0; i--) {
+    try {
+      const v = JSON.parse(blocks[i][1]);
+      if (v && Array.isArray(v.routes)) return v;
+      if (v && typeof v.path === 'string') return { routes: [v] };
+      if (v && Array.isArray(v.results)) return { results: v.results };
+      if (v && Array.isArray(v.items)) return { plan: v };
+    } catch {
+      /* 다음 블록 */
+    }
+  }
+  return null;
+}
+
+/** 폴더의 *.json 을 정렬 순서로 파싱 적재(parse 실패는 errors 기록). */
+function readJsonDir(dir, list, errors) {
+  let files = [];
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith('.json')).sort();
+  } catch {
+    return;
+  }
+  for (const f of files) {
+    try {
+      const v = readJson(join(dir, f), ROUTE_FILE_MAX_BYTES);
+      if (Array.isArray(v)) list.push(...v);
+      else list.push(v);
+    } catch (e) {
+      errors.push(`${f} 파싱 실패: ${e.message}`.slice(0, 300));
+    }
+  }
+}
+
+/** 산출 폴더 수집 → artifact {map, routes[], results[], plan, retest, partial, errors[], browser}.
+ *  feature_map 은 routes/map 을, QA 페이즈는 results/plan/retest 를 기록한다(서버가 페이즈별 해석). */
+export function collectArtifact({ outDir, routesDir, resultsDir, browser, finalText, partial }) {
+  const errors = [];
+  let map = null;
+  const mapPath = join(outDir, 'map.json');
+  if (existsSync(mapPath)) {
+    try {
+      map = readJson(mapPath, ROUTE_FILE_MAX_BYTES);
+    } catch (e) {
+      errors.push(`map.json 파싱 실패: ${e.message}`.slice(0, 300));
+    }
+  } else if (!resultsDir) {
+    errors.push('map.json 없음(요약·커버리지 누락)');
+  }
+
+  const routes = [];
+  readJsonDir(routesDir, routes, errors);
+  const results = [];
+  if (resultsDir) readJsonDir(resultsDir, results, errors);
+
+  let plan = null;
+  let retest = null;
+  for (const [name, key] of [['plan.json', 'plan'], ['retest.json', 'retest']]) {
+    const p = join(outDir, name);
+    if (existsSync(p)) {
+      try {
+        const v = readJson(p, ROUTE_FILE_MAX_BYTES);
+        if (key === 'plan') plan = v; else retest = v;
+      } catch (e) {
+        errors.push(`${name} 파싱 실패: ${e.message}`.slice(0, 300));
+      }
+    }
+  }
+
+  if (!routes.length && !results.length && !plan && !retest) {
+    const fb = fallbackFromText(finalText);
+    if (fb) {
+      if (fb.routes) routes.push(...fb.routes);
+      if (fb.results) results.push(...fb.results);
+      if (fb.map && !map) map = fb.map;
+      errors.push('산출 파일이 없어 최종 보고의 JSON 블록을 사용');
+    }
+  }
+
+  const artifact = { map, routes, results, plan, retest, partial: Boolean(partial), errors, browser };
+  // 본문 상한 — 초과 시 뒤쪽 라우트/결과부터 제외(Claude 는 핵심 항목부터 기록한다).
+  let size = Buffer.byteLength(JSON.stringify(artifact));
+  while (size > ARTIFACT_MAX_BYTES && (artifact.routes.length > 1 || artifact.results.length > 1)) {
+    if (artifact.routes.length >= artifact.results.length) artifact.routes.pop();
+    else artifact.results.pop();
+    artifact.partial = true;
+    size = Buffer.byteLength(JSON.stringify(artifact));
+  }
+  return artifact;
+}
+
+/** 저장소 변경 감지(읽기 전용 위반 경고용) — git 저장소가 아니면 null. */
+export async function porcelain(cwd) {
+  try {
+    const { stdout } = await exec('git', ['status', '--porcelain'], { cwd, maxBuffer: 8 * 1024 * 1024 });
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "e2e-agent-runner",
-  "version": "1.0.2",
-  "description": "suseona e2e 작업 에이전트 로컬 러너 — 내 컴퓨터의 Claude Code 로 구현→테스트→리뷰→배포를 자동 수행",
+  "version": "1.2.0",
+  "description": "suseona e2e 작업 에이전트 로컬 러너 — 내 컴퓨터의 Claude Code 로 구현→테스트→리뷰→배포와 웹사이트 기능 지도 추출을 자동 수행",
   "type": "module",
   "license": "UNLICENSED",
   "private": false,
@@ -17,6 +17,7 @@
     "api.mjs",
     "claude.mjs",
     "git.mjs",
+    "discover.mjs",
     "README.md"
   ],
   "repository": {

package/runner.mjs

@@ -17,6 +17,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { api, runnerIdFromToken, sleep } from './api.mjs';
 import { parsePhaseMarker, probeClaude, runClaude } from './claude.mjs';
+import { collectArtifact, countRouteFiles, porcelain, prepareDiscover } from './discover.mjs';
 import {
   commitCount, ensureTaskBranch, escapeTaskBranch, GitError, mergeToBase, preflight, probeFolder, taskBranchName,
 } from './git.mjs';
@@ -49,6 +50,9 @@ const STEP_TIMEOUT_S = num(process.env.RUNNER_STEP_TIMEOUT_S, 2700); // 서버 w
 const DEPLOY_TIMEOUT_S = num(process.env.DEPLOY_TIMEOUT_S, 600);
 const MAX_TURNS_IMPLEMENT = num(process.env.MAX_TURNS_IMPLEMENT, 150);
 const MAX_TURNS_OTHER = num(process.env.MAX_TURNS_OTHER, 60);
+const MAX_TURNS_DISCOVER = num(process.env.MAX_TURNS_DISCOVER, 500);
+// 기능 지도는 사이트 규모에 비례해 길다 — 서버 와치독은 하트비트(30s)로 갱신되므로 이보다 길어도 안전.
+const DISCOVER_TIMEOUT_S = num(process.env.DISCOVER_TIMEOUT_S, 5400);
 const BUSY_PROBE_POLL_S = 10; // 단계 실행 중 경로 확인(probe) 폴링 주기
 
 function num(v, dflt) {
@@ -162,6 +166,8 @@ async function handleStep({ step, task, project }) {
       result = await runImplement({ step, task, project, buf, cancelled });
     } else if (step.phase === 'deploy') {
       result = await runDeploy({ step, task, project, buf, cancelled });
+    } else if (step.phase === 'discover' || step.phase.startsWith('qa_')) {
+      result = await runDiscover({ step, task, project, buf, cancelled });
     } else {
       // test / remediate / review — 서버 프롬프트(prompt_md)·세션(resume) 그대로 실행.
       result = await runPhase({ step, task, project, buf, cancelled });
@@ -178,6 +184,8 @@ async function handleStep({ step, task, project }) {
       cancelled: Boolean(cancelledNow),
       // implement 전용 — 작업 브랜치 커밋 수(무변경 단축 신호). 다른 페이즈는 미첨부.
       commits: result.commits,
+      // discover 전용 — 기능 지도 산출물(서버가 정규화·기록).
+      artifact: result.artifact,
       usage: result.usage ?? undefined,
     });
     log(`단계 종결: ${task.id.slice(0, 8)}/${step.phase} → ${cancelledNow ? 'cancelled' : result.ok ? 'done' : 'fail'}`);
@@ -214,6 +222,67 @@ async function runImplement({ step, task, project, buf, cancelled }) {
   return { ...result, commits };
 }
 
+/** discover — 기능 지도 추출·QA 페이즈(qa_run/qa_plan/qa_verify — 읽기 전용). 브랜치·프리플라이트
+ *  없이 프로젝트 폴더에서 claude 를 브라우저 MCP 와 함께 실행하고, 임시 산출 폴더의 기록분을
+ *  artifact 로 수집해 보고한다. 시간 초과·실패여도 수집분이 있으면 보고(서버가 partial 로 보존).
+ *  qa_plan 은 직전 qa_run 세션을 resume 한다(문제를 직접 관찰한 컨텍스트 위에서 계획). */
+async function runDiscover({ step, task, project, buf, cancelled }) {
+  if (!state.claudeBin) throw new Error('claude CLI 를 찾을 수 없습니다 — CLAUDE_BIN 확인 후 러너를 재시작하세요.');
+  const isQa = step.phase.startsWith('qa_');
+  const prep = prepareDiscover({ siteUrl: project.site_url, results: isQa });
+  log(`${isQa ? 'QA' : '기능 지도'} 탐색 시작: ${project.site_url ?? '(사이트 없음)'} — browser=${prep.browser}, out=${prep.outDir}`);
+  buf.push(step.id, 'status', { event: 'fm_started', phase: step.phase, browser: prep.browser });
+  const before = await porcelain(project.folder_path);
+  let lastCount = 0;
+  const progress = setInterval(() => {
+    const n = countRouteFiles(prep.routesDir) + countRouteFiles(prep.resultsDir);
+    if (n !== lastCount) {
+      lastCount = n;
+      buf.push(step.id, 'status', { event: 'fm_progress', phase: step.phase, files: n });
+    }
+  }, 10_000);
+  try {
+    const result = await runClaude({
+      cwd: project.folder_path,
+      prompt: `${step.prompt_md}\n${prep.promptAddon}\n`,
+      resumeSessionId: step.phase === 'qa_plan' ? step.session_id : null,
+      maxTurns: MAX_TURNS_DISCOVER,
+      timeoutS: DISCOVER_TIMEOUT_S,
+      extraArgs: prep.extraArgs,
+      onEvent: (ev) => buf.push(step.id, ev.kind, ev.data),
+      shouldCancel: cancelled,
+      onSessionId: (sessionId) => {
+        buf.taskMeta = { session_id: sessionId };
+      },
+    });
+    const flag = parsePhaseMarker(result.finalText);
+    const artifact = collectArtifact({
+      outDir: prep.outDir,
+      routesDir: prep.routesDir,
+      browser: prep.browser,
+      finalText: result.finalText,
+      partial: !result.ok || flag !== 'pass',
+    });
+    buf.push(step.id, 'status', {
+      event: 'fm_collected', phase: step.phase,
+      routes: artifact.routes.length, results: artifact.results.length, errors: artifact.errors.slice(0, 5),
+    });
+    const after = await porcelain(project.folder_path);
+    if (before !== null && after !== null && after !== before) {
+      buf.push(step.id, 'status', {
+        event: 'repo_modified',
+        note: '읽기 전용 탐색 중 저장소가 변경되었습니다 — git status 로 확인하세요.',
+        files: after.split('\n').slice(0, 8),
+      });
+    }
+    log(`기능 지도 수집: 라우트 ${artifact.routes.length}개, 오류 ${artifact.errors.length}건`);
+    return { ...result, flag, artifact };
+  } finally {
+    clearInterval(progress);
+    prep.cleanup();
+  }
+}
+
 /** test/remediate/review 공통 — prompt_md + resume 세션. */
 async function runPhase({ step, task, project, buf, cancelled, extraMeta }) {
   if (!state.claudeBin) throw new Error('claude CLI 를 찾을 수 없습니다 — CLAUDE_BIN 확인 후 러너를 재시작하세요.');