@ahnseungchan/device-farm 0.0.0-stage → 0.1.0

package/dist/server-3NM7ODUG.js

@@ -0,0 +1,251 @@
+import {
+  defaultGuard,
+  loadExploreInputs
+} from "./chunk-AVECSGEH.js";
+import "./chunk-UAHWEUDI.js";
+import "./chunk-F6PZOBU6.js";
+import "./chunk-Q6CXF3NJ.js";
+import {
+  buildRecording
+} from "./chunk-JD2L6T7E.js";
+import {
+  addCandidate,
+  mapRulesOf,
+  readReady
+} from "./chunk-PLMSQ5KF.js";
+import {
+  recordScreenMap
+} from "./chunk-F4TMB4WY.js";
+import {
+  buttonCheckLimits,
+  hasForbiddenWord,
+  listActionsScript,
+  screenTextsScript,
+  stepsOf
+} from "./chunk-SWW42KTA.js";
+import {
+  listDevices
+} from "./chunk-JZDYF3HL.js";
+import {
+  execFileText,
+  openAndroidDriver
+} from "./chunk-AXQNUPGC.js";
+import {
+  isLoginPath,
+  loadAppConfig,
+  loadDotEnv,
+  resolveAppConfigFile,
+  sleep,
+  webOrigin
+} from "./chunk-NLX3V7ZJ.js";
+import "./chunk-NJNTEWXE.js";
+
+// apps/mcp/src/server.ts
+import { createHash } from "crypto";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import path from "path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// packages/core/src/agent/device-session.ts
+var defaultMaxActions = 40;
+var maxListedActions = 40;
+function createDeviceSession(driver, options = {}) {
+  const maxActions = options.maxActions ?? defaultMaxActions;
+  const now = options.now ?? Date.now;
+  const events = [];
+  const findings = [];
+  let actions = 0;
+  const { homePath, loginPaths, appErrorText, guard } = driver.app;
+  const forbidden = (name) => hasForbiddenWord(name, guard.forbiddenButtonWords);
+  let lastPath = homePath;
+  let lastActions = [];
+  const look = async () => {
+    const path2 = await driver.currentPath();
+    const all = await driver.evaluate(listActionsScript).catch(() => []);
+    const unique = /* @__PURE__ */ new Map();
+    for (const item of all) if (item.role !== "input" && !forbidden(item.name)) unique.set(`${item.role}:${item.name}`, { role: item.role, name: item.name });
+    const texts = await driver.evaluate(screenTextsScript).catch(() => []);
+    const blocked = options.takeBlocked?.() ?? [];
+    const flags = [
+      isLoginPath(path2, loginPaths) ? "\uB85C\uADF8\uC778 \uD654\uBA74\uC73C\uB85C \uD295\uAE40" : null,
+      await driver.hasText(appErrorText).catch(() => false) ? `\uC571 \uC624\uB958 \uD45C\uC2DC(${appErrorText})` : null,
+      blocked.length > 0 ? `\uB9C9\uC740 \uC4F0\uAE30 \uC694\uCCAD: ${blocked.join(", ")}` : null
+    ].filter((flag) => flag !== null);
+    lastPath = path2;
+    lastActions = [...unique.values()].slice(0, maxListedActions);
+    return { path: path2, texts, flags, actions: lastActions, remainingActions: Math.max(0, maxActions - actions) };
+  };
+  const spend = () => {
+    if (actions >= maxActions) throw new Error("\uB204\uB97C \uC218 \uC788\uB294 \uD69F\uC218\uB97C \uB2E4 \uC37C\uC2B5\uB2C8\uB2E4. \uD0D0\uC0C9\uC744 \uB05D\uB0B4\uC138\uC694.");
+    actions += 1;
+  };
+  return {
+    events,
+    findings,
+    actions: () => actions,
+    look,
+    press: async (role, name) => {
+      if (forbidden(name)) throw new Error(`\u300C${name}\u300D\uC740 \uB204\uB97C \uC218 \uC5C6\uB294 \uBC84\uD2BC\uC785\uB2C8\uB2E4.`);
+      if (!lastActions.some((item) => item.role === role && item.name === name)) {
+        throw new Error(`\u300C${name}\u300D(${role})\uC740 \uB9C8\uC9C0\uB9C9 \uBCF4\uAE30 \uBAA9\uB85D\uC5D0 \uC5C6\uC2B5\uB2C8\uB2E4. \uD654\uBA74\uC744 \uB2E4\uC2DC \uBCF4\uC138\uC694.`);
+      }
+      spend();
+      const from = lastPath;
+      await driver.clickButton(name, role);
+      await sleep(buttonCheckLimits.settleMs);
+      const view = await look();
+      events.push({ type: "click", at: now(), from, role, name, to: view.path, texts: view.texts });
+      return view;
+    },
+    goHome: async () => {
+      if (!driver.goHome) throw new Error("\uC774 \uAE30\uAE30\uB294 \uD648\uC73C\uB85C \uAC08 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.");
+      spend();
+      const from = lastPath;
+      await driver.goHome();
+      const view = await look();
+      events.push({ type: "jump", at: now(), from, to: view.path });
+      return view;
+    },
+    reportIssue: async (description) => {
+      const screenshot = await driver.screenshot().catch(() => void 0);
+      findings.push({ path: lastPath, description, screenshot });
+    }
+  };
+}
+
+// apps/mcp/src/server.ts
+var agentIdHashLength = 8;
+var userProject = process.cwd();
+var farmRoot = process.env.FARM_ROOT ?? path.resolve(path.dirname(new URL(import.meta.url).pathname), "../../..");
+var userConfig = path.join(userProject, "farm.config.ts");
+var configFile = process.env.FARM_CONFIG ? resolveAppConfigFile(process.env, userProject) : existsSync(userConfig) ? userConfig : resolveAppConfigFile(process.env, farmRoot);
+process.chdir(farmRoot);
+loadDotEnv();
+var app = await loadAppConfig(configFile, (line) => console.error(line));
+var farmRunsUrl = `http://127.0.0.1:${Number(process.env.FARM_PORT) || 5173}/api/devices/runs/latest`;
+var active = null;
+var text = (value) => ({ content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 1) }] });
+var failure = (error) => ({ ...text(error instanceof Error ? error.message : String(error)), isError: true });
+function requireActive() {
+  if (!active) throw new Error("\uD0D0\uC0C9\uC774 \uC2DC\uC791\uB418\uC9C0 \uC54A\uC558\uC2B5\uB2C8\uB2E4. device_start\uBD80\uD130 \uBD80\uB974\uC138\uC694.");
+  return active;
+}
+async function guarded(work) {
+  try {
+    return text(await work());
+  } catch (error) {
+    return failure(error);
+  }
+}
+async function farmBusy() {
+  const response = await fetch(farmRunsUrl).catch(() => null);
+  if (!response?.ok) return false;
+  const run = await response.json().catch(() => null);
+  return Boolean(run && run.finishedAt === null);
+}
+async function start(task, deviceId, maxActions) {
+  if (active) throw new Error(`\uC774\uBBF8 \uD0D0\uC0C9 \uC911\uC785\uB2C8\uB2E4: ${active.task}. device_finish\uB85C \uB05D\uB0B8 \uB4A4 \uC2DC\uC791\uD558\uC138\uC694.`);
+  if (await farmBusy()) throw new Error("\uB514\uBC14\uC774\uC2A4\uD31C \uC810\uAC80\uC774 \uB3C4\uB294 \uC911\uC774\uB77C \uAE30\uAE30\uB97C \uC4F8 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.");
+  const devices = (await listDevices(execFileText, app.appIds.dev)).filter((device2) => device2.platform === "android");
+  const device = deviceId ? devices.find((item) => item.id === deviceId) : devices[0];
+  if (!device) throw new Error(deviceId ? `\uC5F0\uACB0\uB41C Android \uAE30\uAE30\uAC00 \uC544\uB2D9\uB2C8\uB2E4: ${deviceId}` : "\uC5F0\uACB0\uB41C Android \uAE30\uAE30\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4. iOS\uB294 \uC4F0\uAE30 \uC694\uCCAD \uCC28\uB2E8\uC774 \uC5C6\uC5B4 \uC544\uC9C1 \uD0D0\uC0C9\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.");
+  const origin = webOrigin(app, "dev");
+  const driver = await openAndroidDriver(device.id, app.appIds.dev, origin, app);
+  const blocked = [];
+  const unguard = await defaultGuard(driver, origin, loadExploreInputs().allowlist, (request) => blocked.push(`${request.method} ${request.path}`)).catch(async (error) => {
+    await driver.close();
+    throw error;
+  });
+  const session = createDeviceSession(driver, { maxActions, takeBlocked: () => blocked.splice(0) });
+  active = { task, driver, session, unguard };
+  if (!driver.goHome) throw new Error("\uD648\uC73C\uB85C \uAC08 \uC218 \uC5C6\uB294 \uB4DC\uB77C\uC774\uBC84\uC785\uB2C8\uB2E4.");
+  await driver.goHome();
+  return { device: `${device.model} (${device.id})`, task, maxActions, screen: await session.look() };
+}
+async function finish(summary) {
+  const { task, driver, session, unguard } = requireActive();
+  active = null;
+  try {
+    const recording = buildRecording(session.events, app.homePath, mapRulesOf(app));
+    for (const screen of recording.screens) recordScreenMap(screen.from, screen.buttons);
+    const dir = path.resolve("test-results/agent", (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-"));
+    mkdirSync(dir, { recursive: true });
+    const findings = session.findings.map((finding, index) => {
+      const screenshot = finding.screenshot ? `finding-${index + 1}.png` : void 0;
+      if (finding.screenshot && screenshot) writeFileSync(path.join(dir, screenshot), finding.screenshot);
+      return { path: finding.path, description: finding.description, screenshot };
+    });
+    writeFileSync(path.join(dir, "report.json"), `${JSON.stringify({ task, summary, actions: session.actions(), findings, events: session.events, cut: recording.cut }, null, 2)}
+`);
+    const steps = stepsOf(recording.steps, app.guard.forbiddenClickNames);
+    let candidate;
+    if (typeof steps === "string") {
+      candidate = `\uD50C\uB85C\uC6B0 \uD6C4\uBCF4\uB85C \uC62C\uB9AC\uC9C0 \uC54A\uC74C: ${recording.cut ?? steps}`;
+    } else {
+      const id = `agent-${createHash("sha256").update(JSON.stringify(steps)).digest("hex").slice(0, agentIdHashLength)}`;
+      const proposal = readReady().some((flow2) => flow2.id === id) ? "update" : "create";
+      const flow = { id, name: `\uD0D0\uC0C9: ${task}`, source: "recorded", status: "generated", prd: "\uC5D0\uC774\uC804\uD2B8 \uD0D0\uC0C9", requirement: task, proposal, steps };
+      addCandidate(flow);
+      candidate = `\uD50C\uB85C\uC6B0 \uD6C4\uBCF4 \u300C${flow.name}\u300D(${id})\uB97C \uC62C\uB838\uC2B5\uB2C8\uB2E4. \uB514\uBC14\uC774\uC2A4\uD31C \uD50C\uB85C\uC6B0 \uD0ED\uC5D0\uC11C \uD655\uC815\uD560 \uC218 \uC788\uC2B5\uB2C8\uB2E4.`;
+    }
+    return { report: path.relative(process.cwd(), path.join(dir, "report.json")), actions: session.actions(), findings, mapScreens: recording.screens.length, candidate };
+  } finally {
+    await unguard().catch(() => void 0);
+    await driver.close().catch(() => void 0);
+  }
+}
+var server = new McpServer({ name: "device-farm", version: "0.1.0" });
+var roleSchema = z.enum(["button", "link"]);
+server.registerTool(
+  "device_start",
+  {
+    description: `${app.name} Android dev \uC571 \uD0D0\uC0C9\uC744 \uC2DC\uC791\uD55C\uB2E4. \uC4F0\uAE30 \uC694\uCCAD \uCC28\uB2E8\uC744 \uCF1C\uACE0 \uD648 \uD0ED(${app.homeTabName})\uC73C\uB85C \uAC04 \uB4A4 \uD654\uBA74\uC744 \uB3CC\uB824\uC900\uB2E4. \uAD6C\uB9E4\xB7\uACB0\uC81C\xB7\uCD9C\uAE08\xB7\uC2E0\uCCAD\xB7\uD0C8\uD1F4 \uAC19\uC740 \uBC84\uD2BC\uC740 \uBAA9\uB85D\uC5D0\uC11C \uBE60\uC9C0\uACE0 \uB20C\uB7EC\uB3C4 \uAC70\uC808\uB41C\uB2E4. \uB05D\uB098\uBA74 \uBC18\uB4DC\uC2DC device_finish\uB97C \uBD80\uB978\uB2E4.`,
+    inputSchema: {
+      task: z.string().describe("\uD0D0\uC0C9 \uBAA9\uD45C. \uC608: \uD034\uC988 \uD654\uBA74\uC744 \uB098\uAC14\uB2E4 \uB2E4\uC2DC \uB4E4\uC5B4\uC62C \uB54C \uC0C1\uD0DC\uAC00 \uC720\uC9C0\uB418\uB294\uC9C0"),
+      device: z.string().optional().describe("Android serial. \uC5C6\uC73C\uBA74 \uC5F0\uACB0\uB41C \uCCAB \uAE30\uAE30"),
+      maxActions: z.number().int().positive().optional().describe(`\uB204\uB974\uAE30\xB7\uD648 \uC774\uB3D9 \uCD5C\uB300 \uD69F\uC218 (\uAE30\uBCF8 ${defaultMaxActions})`)
+    }
+  },
+  async ({ task, device, maxActions }) => guarded(() => start(task, device, maxActions ?? defaultMaxActions))
+);
+server.registerTool(
+  "device_look",
+  { description: "\uC9C0\uAE08 \uD654\uBA74\uC758 \uACBD\uB85C, \uC81C\uBAA9\xB7\uD31D\uC5C5 \uBB38\uAD6C, \uACBD\uACE0(\uC571 \uC624\uB958\xB7\uB85C\uADF8\uC778 \uD295\uAE40\xB7\uB9C9\uC740 \uC4F0\uAE30 \uC694\uCCAD), \uB204\uB97C \uC218 \uC788\uB294 \uBC84\uD2BC\xB7\uB9C1\uD06C \uBAA9\uB85D, \uB0A8\uC740 \uD69F\uC218\uB97C \uBCF8\uB2E4." },
+  async () => guarded(() => requireActive().session.look())
+);
+server.registerTool(
+  "device_press",
+  {
+    description: "\uB9C8\uC9C0\uB9C9 device_look \uBAA9\uB85D\uC5D0 \uC788\uB294 \uBC84\uD2BC\xB7\uB9C1\uD06C\uB97C \uC774\uB984 \uADF8\uB300\uB85C \uB204\uB978\uB2E4. \uB204\uB978 \uB4A4 \uD654\uBA74\uC744 \uB3CC\uB824\uC900\uB2E4.",
+    inputSchema: { role: roleSchema, name: z.string().describe("\uBAA9\uB85D\uC758 name\uC744 \uAE00\uC790 \uADF8\uB300\uB85C") }
+  },
+  async ({ role, name }) => guarded(() => requireActive().session.press(role, name))
+);
+server.registerTool(
+  "device_go_home",
+  { description: `\uC5F4\uB9B0 \uD654\uBA74\uC744 \uBAA8\uB450 \uB2EB\uACE0 \uD648(${app.homeTabName} \uD0ED)\uC73C\uB85C \uAC04\uB2E4. \uB9C9\uD614\uAC70\uB098 \uCC98\uC74C\uBD80\uD130 \uB2E4\uC2DC \uD574 \uBCFC \uB54C \uC4F4\uB2E4.` },
+  async () => guarded(() => requireActive().session.goHome())
+);
+server.registerTool(
+  "device_report_issue",
+  {
+    description: "\uC9C0\uAE08 \uD654\uBA74\uC5D0\uC11C \uBC84\uADF8\uB85C \uBCF4\uC774\uB294 \uAC83\uC744 \uC2A4\uD06C\uB9B0\uC0F7\uACFC \uAC19\uC774 \uB0A8\uAE34\uB2E4. \uBB34\uC5C7\uC744 \uD588\uB354\uB2C8 \uBB34\uC5C7\uC774 \uC774\uC0C1\uD588\uB294\uC9C0 \uAD6C\uCCB4\uC801\uC73C\uB85C \uC4F4\uB2E4. \uB514\uC790\uC778 \uCDE8\uD5A5\uC740 \uB0A8\uAE30\uC9C0 \uC54A\uB294\uB2E4.",
+    inputSchema: { description: z.string() }
+  },
+  async ({ description }) => guarded(async () => (await requireActive().session.reportIssue(description), "\uAE30\uB85D\uD588\uC2B5\uB2C8\uB2E4."))
+);
+server.registerTool(
+  "device_finish",
+  {
+    description: "\uD0D0\uC0C9\uC744 \uB05D\uB0B8\uB2E4. \uD654\uBA74 \uC9C0\uB3C4\uC5D0 \uD569\uCE58\uACE0, \uD648\uBD80\uD130 \uB2E4\uC2DC \uB3CC \uC218 \uC788\uC73C\uBA74 \uD50C\uB85C\uC6B0 \uD6C4\uBCF4\uB85C \uC62C\uB9AC\uACE0, \uC774\uC0C1 \uD6C4\uBCF4\xB7\uC2A4\uD06C\uB9B0\uC0F7\uC744 \uBCF4\uACE0\uC11C\uB85C \uB0A8\uAE34\uB2E4.",
+    inputSchema: { summary: z.string().describe("\uD55C \uC77C\uACFC \uCC3E\uC740 \uAC83 \uC694\uC57D") }
+  },
+  async ({ summary }) => guarded(() => finish(summary))
+);
+process.stdin.on("close", () => {
+  if (active) void finish("\uC5F0\uACB0\uC774 \uB04A\uACA8 \uB05D\uB0C4").catch((error) => console.error(error));
+});
+await server.connect(new StdioServerTransport());
+console.error("[device-farm] MCP \uC11C\uBC84 \uC900\uBE44\uB428");

package/dist/templates/env.example

@@ -0,0 +1,48 @@
+# 비밀 값과 이 맥에만 해당하는 값. 앱마다 다른 값은 farm.config.ts에 둔다.
+
+# 앱 설정 파일 경로(비우면 작업 폴더의 farm.config.ts → farm.config.example.ts)
+FARM_CONFIG=
+# 화면 서버 포트(비우면 5173)
+FARM_PORT=
+# farm.config.ts의 web·apiOrigin을 이 맥에서만 덮을 때
+FARM_WEB_ORIGIN_DEV=
+FARM_WEB_ORIGIN_PROD=
+FARM_API_ORIGIN=
+# 탐색 허용 목록 후보를 뽑을 OpenAPI 스펙 주소(npm run explore-allowlist)
+FARM_OPENAPI_URL=
+# 디바이스팜 화면에 들어올 수 있는 Tailscale 계정 도메인(쉼표). 비우면 farm.config.ts의 access.allowedDomains
+FARM_ALLOWED_DOMAINS=
+
+# Firebase App Distribution(빌드 받기·새 빌드 감시). 앱 id는 farm.config.ts install.firebase로도 줄 수 있다
+FIREBASE_SERVICE_ACCOUNT=
+FIREBASE_APP_ANDROID_DEV=
+FIREBASE_APP_ANDROID_PROD=
+FIREBASE_APP_IOS_DEV=
+FIREBASE_APP_IOS_PROD=
+
+# App Store Connect(TestFlight 새 빌드 감시, 읽기만)
+ASC_KEY_ID=
+ASC_ISSUER_ID=
+ASC_PRIVATE_KEY_PATH=
+ASC_APP_ID=
+ASC_APP_ID_DEV=
+
+# iOS Appium·WebDriverAgent. 팀 id가 비면 서명 설정 없이 세션을 연다
+APPIUM_URL=
+IOS_TEAM_ID=
+IOS_WDA_BUNDLE_ID=
+
+# 플로우 생성: PRD를 읽을 프론트 체크아웃, OpenAI 호환 LLM
+FLOW_PRD_ROOT=
+FLOW_LLM_API_KEY=
+FLOW_LLM_BASE_URL=
+FLOW_LLM_MODEL=
+
+# 정책·피그마 대조(읽기 전용). cloudId·스페이스는 farm.config.ts policy.confluence로도 줄 수 있다
+CONFLUENCE_EMAIL=
+CONFLUENCE_API_TOKEN=
+CONFLUENCE_CLOUD_ID=
+CONFLUENCE_SPACE_KEY=
+FIGMA_TOKEN=
+# 프론트 배포 브랜치(비우면 farm.config.ts figma.ref)
+FARM_FRONT_REF=

package/dist/templates/farm.config.ts

@@ -0,0 +1,104 @@
+/**
+ * 디바이스팜 앱 설정(`npx device-farm init`이 만든 예시: 가상의 쇼핑 앱 「Sample Shop」).
+ * 값을 내 앱으로 바꾼다. 필수는 name·appIds·homePath·homeTabName·tabPaths뿐이고 나머지는 지워도 된다.
+ * 비밀 값(토큰·키)은 여기 말고 .env에 둔다.
+ */
+import { defineAppConfig, equalWon, formatWon, numberAt, textHas } from "@ahnseungchan/device-farm";
+
+export default defineAppConfig({
+  name: "Sample Shop",
+  // Android 패키지 = iOS 번들 id. 다르면 iosBundleIds로 덮는다.
+  appIds: { dev: "com.example.shop.dev", prod: "com.example.shop" },
+  // 앱 WebView가 여는 웹 주소. 비우면 .env의 FARM_WEB_ORIGIN_DEV·FARM_WEB_ORIGIN_PROD
+  web: { dev: "https://dev.shop.example.com", prod: "https://shop.example.com" },
+  // API 호스트가 웹과 다를 때. 탐색 가드가 내부로 보고, 데이터 QA가 이 주소로 다시 조회한다.
+  apiOrigin: "https://api-dev.shop.example.com",
+
+  // 하단 탭바(웹 링크). 홈 탭을 누르면 homePath로 간다. 플로우는 홈에서 시작한다.
+  homePath: "/home",
+  homeTabName: "홈",
+  tabPaths: { 카테고리: "/category", 혜택: "/benefit", 마이: "/my" },
+  // 화면 상단 뒤로 버튼 이름(aria-label)
+  inPageBackNames: ["뒤로가기"],
+  // 여기로 튕기면 로그인이 풀린 것으로 본다
+  loginPaths: ["/login"],
+  appErrorText: "Application error",
+
+  // 시나리오 경로 → sampleshop://benefit/attendance. 앱이 같은 웹 경로를 WebView 스택으로 연다고 본다.
+  deepLink: { scheme: "sampleshop", homeHost: "home" },
+  android: {
+    // 이 액티비티가 아닌 앱 화면(네이티브 오퍼월 등)이 위에 있으면 뒤로 키로 닫는다. 비우면 닫지 않는다.
+    mainActivity: "com.example.shop.MainActivity",
+  },
+  webview: {
+    // 열린 WebView 스택을 모두 닫는 앱 브리지(예: flutter_inappwebview 핸들러). 비우면 닫지 않는다.
+    stackResetScript: "window.appBridge && window.appBridge.callHandler && window.appBridge.callHandler('stackReset')",
+    sheetCloseName: "닫기",
+  },
+
+  guard: {
+    // 기본 금지어(구매·결제·송금·출금·탈퇴…)에 더한다
+    extraForbiddenButtonWords: ["쿠폰 사용"],
+    extraForbiddenApiPatterns: [/coupon\/use/i],
+    // 앱이 켜질 때마다 보내 막으면 안 되는 쓰기 요청(푸시 토큰 저장 등)
+    pushTokenRequests: [{ method: "POST", path: "/v1/users/{userId}/push-token" }],
+  },
+
+  // 고정 주소 화면 점검. excludedScenarioPaths는 앞 단계가 있어야 열리는 완료·중간 화면
+  scenarios: [
+    { path: "/home", name: "로그인 후 홈 화면이 열린다", when: "홈 화면을 연다", then: "홈 화면이 보인다" },
+    { path: "/category", name: "로그인 후 카테고리 화면이 열린다", when: "카테고리 화면을 연다", then: "카테고리 화면이 보인다" },
+    { path: "/benefit/attendance", name: "로그인 후 출석체크 화면이 열린다", when: "출석체크를 연다", then: "출석 화면이 보인다" },
+    { path: "/my", name: "로그인 후 마이 화면이 열린다", when: "마이 화면을 연다", then: "마이 화면이 보인다" },
+    { path: "/order/complete", name: "로그인 후 주문 완료 화면이 열린다", when: "주문 완료 화면을 연다", then: "주문 완료 화면이 보인다" },
+  ],
+  excludedScenarioPaths: ["/order/complete"],
+
+  // 데이터 QA(선택): 화면이 부르는 GET API를 다시 불러 화면 글자와 맞춰 본다. LLM 없이 규칙으로만 판정한다.
+  qa: {
+    sessionPath: "/api/auth/session",
+    screens: [
+      {
+        path: "/cart",
+        name: "장바구니",
+        apis: { cart: "/v1/users/{userId}/cart" },
+        rules: [
+          {
+            id: "total-equals-items",
+            title: "합계 = 항목 금액 합",
+            check: (context) => {
+              const items = (context.responses.cart as { items?: { priceWon: number }[] } | undefined)?.items;
+              if (!Array.isArray(items)) throw new Error("cart.items가 배열이 아닙니다.");
+              return equalWon("합계", numberAt(context, "cart", "totalWon"), items.reduce((sum, item) => sum + item.priceWon, 0));
+            },
+          },
+          {
+            id: "total-shown",
+            title: "받은 합계가 화면에 그대로 보인다",
+            check: (context) => {
+              const shown = `${formatWon(numberAt(context, "cart", "totalWon"))}원`;
+              return textHas(context.text, shown) ? null : `화면에 없음: 합계 「${shown}」`;
+            },
+          },
+        ],
+      },
+    ],
+  },
+
+  // 정책 대조(선택): Confluence 스페이스에서 제목에 titleQuery가 든 페이지를 정책 정본으로 본다. 토큰은 .env
+  policy: {
+    confluence: { cloudId: "00000000-0000-0000-0000-000000000000", spaceKey: "SHOP", titleQuery: "정책", siteUrl: "https://example.atlassian.net/wiki" },
+  },
+  // 피그마 대조(선택): 프론트(Next.js App Router) 체크아웃에서 화면 → 피그마 노드를 뽑는다. 토큰은 .env의 FIGMA_TOKEN
+  figma: { frontRepo: "", ref: "origin/main", appDir: "app" },
+
+  // 빌드 받기(선택): Firebase App Distribution 앱 id(비우면 .env), iOS dev는 TestFlight에서 깔기
+  install: {
+    sources: { ios: { dev: "testflight" } },
+    testflightDevAppName: "Sample Shop DEV",
+  },
+  // WDA 서명 팀·번들 id(비우면 .env의 IOS_TEAM_ID·IOS_WDA_BUNDLE_ID)
+  ios: {},
+  // 디바이스팜 화면에 들어올 수 있는 Tailscale 계정 도메인(비우면 이 맥에서만)
+  access: { allowedDomains: ["example.com"] },
+});