@usercase/mcp 0.0.0-stage → 0.2.1-next.0

package/mcp/workspace.js

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * 고객 저장소의 `.usercase/` — 사람 파일과 방문 기록(PLAN.md "사람 파일은 어디에").
+ *
+ * - `people.json`   사이트·사이트 설명·가상 사용자들. 고객이 열어 고치고, git 에 넣을지 스스로 정한다
+ * - `runs/*.jsonl`  방문 기록. 걸음마다 이유가 남는다 — "왜 여기서 나갔지" 를 확인하는 근거
+ * - `sessions/`     데모 계정마다 로그인 세션 하나. **로그인 그 자체라** git 에서 뺀다
+ * - `settings.json` 사용자가 고른 것 — 사이트에 쓰는 것을 보낼지(writes)
+ *
+ * MCP 서버는 AI 도구가 저장소 폴더에서 띄우므로 기본 위치는 cwd 다. `USERCASE_DIR` 로 바꾼다.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const DIR = process.env.USERCASE_DIR || path.join(process.cwd(), ".usercase");
+
+/** 0.1.x 까지는 이름이 earningbirds 라 `.earningbirds/` 였다. 새 폴더가 없을 때 한 번 옮긴다 */
+(function migrateDir() {
+  if (process.env.USERCASE_DIR) return;
+  const old = path.join(process.cwd(), ".earningbirds");
+  if (!fs.existsSync(old) || fs.existsSync(DIR)) return;
+  try {
+    fs.renameSync(old, DIR);
+  } catch {} // 다른 프로그램이 잡고 있으면 새 폴더로 새로 시작한다
+})();
+const PEOPLE = path.join(DIR, "people.json");
+const RUNS = path.join(DIR, "runs");
+const SESSION = path.join(DIR, "session.json");
+const SETTINGS = path.join(DIR, "settings.json");
+
+/** 사용자가 고른 것. 없으면 기본 — 사이트에 쓰는 것은 보내지 않는다 */
+function loadSettings() {
+  try {
+    return { writes: "block", ...JSON.parse(fs.readFileSync(SETTINGS, "utf8")) };
+  } catch {
+    return { writes: "block" };
+  }
+}
+
+function saveSettings(patch) {
+  ensure();
+  const next = { ...loadSettings(), ...patch };
+  fs.writeFileSync(SETTINGS, JSON.stringify(next, null, 2));
+  return next;
+}
+
+/**
+ * 데모 계정마다 세션 하나 — `sessions/<계정>.json`. 회원 방문자를 계정들에 나눠 앉힌다.
+ * 한 계정을 모두가 같이 쓰면 관심목록·기록이 한 사람 것이 된다(10/14).
+ * 계정 이름은 사용자가 알아볼 짧은 이름(a1, a2 …). 비밀번호는 어디에도 없다 — 사용자가 창에서 직접 로그인한다
+ */
+const SESSIONS = path.join(DIR, "sessions");
+const ACCOUNTS_INDEX = path.join(SESSIONS, "index.json");
+const ACCOUNT_NAME = /^[a-z0-9][a-z0-9_-]{0,23}$/i;
+
+const sessionPath = (account) => path.join(SESSIONS, `${account}.json`);
+
+function readIndex() {
+  try {
+    return JSON.parse(fs.readFileSync(ACCOUNTS_INDEX, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+/** 0.1.10 까지는 session.json 하나였다. 계정 a1 로 옮긴다 */
+function migrateSession() {
+  if (!fs.existsSync(SESSION) || fs.existsSync(sessionPath("a1"))) return;
+  fs.mkdirSync(SESSIONS, { recursive: true });
+  fs.renameSync(SESSION, sessionPath("a1"));
+}
+
+/**
+ * 저장된 계정들. status 는 마지막으로 확인한 로그인 상태:
+ * signed_in · signed_out(로그인 안 됨) · expired(방문 중 풀림) · unknown(사이트에 비교할 로그인 링크가 없음) · unchecked
+ */
+function accounts() {
+  migrateSession();
+  if (!fs.existsSync(SESSIONS)) return [];
+  const idx = readIndex();
+  return fs
+    .readdirSync(SESSIONS)
+    .filter((f) => f.endsWith(".json") && f !== "index.json")
+    .map((f) => {
+      const account = f.slice(0, -5);
+      const st = fs.statSync(path.join(SESSIONS, f));
+      const meta = idx[account] || {};
+      return {
+        account,
+        path: path.join(SESSIONS, f),
+        savedAt: st.mtime.toISOString(),
+        ageH: Math.round((Date.now() - st.mtimeMs) / 36e5),
+        // 코드로 본 수명이 지났으면 확인 없이도 만료로 본다
+        status: meta.status === "signed_in" && typeof meta.lifetimeH === "number" && Date.now() > st.mtimeMs + meta.lifetimeH * 36e5 ? "expired" : meta.status || "unchecked",
+        note:
+          meta.status === "signed_in" && typeof meta.lifetimeH === "number" && Date.now() > st.mtimeMs + meta.lifetimeH * 36e5
+            ? `its session lifetime (${meta.lifetimeH}h) has passed`
+            : meta.note || null,
+        checkedAt: meta.checkedAt || null,
+        via: meta.via || null,
+        lifetimeH: typeof meta.lifetimeH === "number" ? meta.lifetimeH : null,
+        // 수명을 알면 언제 끝나나(저장한 때부터)
+        expiresAt: typeof meta.lifetimeH === "number" ? new Date(st.mtimeMs + meta.lifetimeH * 36e5).toISOString() : null,
+      };
+    })
+    .sort((a, b) => a.account.localeCompare(b.account, undefined, { numeric: true }));
+}
+
+/**
+ * @param extra  같이 남길 것 — via(어느 창으로 로그인했나: chrome·playwright), lifetimeH(코드로 본 세션 수명, 시간)
+ *               안 주면 전에 적은 것을 둔다
+ */
+function setAccountStatus(account, status, note = null, extra = {}) {
+  ensure();
+  const idx = readIndex();
+  idx[account] = { ...(idx[account] || {}), ...extra, status, note, checkedAt: new Date().toISOString() };
+  fs.writeFileSync(ACCOUNTS_INDEX, JSON.stringify(idx, null, 2));
+}
+
+/** 다음 빈 계정 이름 */
+function nextAccount() {
+  const have = new Set(accounts().map((a) => a.account));
+  let i = 1;
+  while (have.has(`a${i}`)) i++;
+  return `a${i}`;
+}
+
+function ensure() {
+  fs.mkdirSync(RUNS, { recursive: true });
+  fs.mkdirSync(SESSIONS, { recursive: true });
+  const gi = path.join(DIR, ".gitignore");
+  // 방문 기록에는 사람 정보와 사이트 글자가 들어가고 세션은 로그인 그 자체다. 경로 화면(paths/)도 로그인한 화면일 수 있다. 저장소에 올라가지 않게
+  if (!fs.existsSync(gi)) fs.writeFileSync(gi, "session.json\nsessions/\nruns/\npaths/\n");
+  else {
+    let cur = fs.readFileSync(gi, "utf8");
+    for (const line of ["sessions/", "paths/"])
+      if (!new RegExp(`^${line.replace("/", "\\/")}$`, "m").test(cur)) {
+        fs.appendFileSync(gi, (cur.endsWith("\n") ? "" : "\n") + line + "\n");
+        cur = fs.readFileSync(gi, "utf8");
+      }
+  }
+}
+
+function loadPeople() {
+  if (!fs.existsSync(PEOPLE)) return { site: null, siteAbout: null, people: [] };
+  const doc = JSON.parse(fs.readFileSync(PEOPLE, "utf8"));
+  // 예전 파일은 사람마다 이름이 있었다 — 번호로 바꾼다. 고유 값이 없던 사람은 여기서 받고 바로 적어 둔다(읽을 때마다 바뀌면 안 된다)
+  const lacked = (doc.people ?? []).some((p) => !p.uid);
+  doc.people = require("../src/persona/people.js").withIds(doc.people ?? [], []).existing;
+  if (lacked) savePeople(doc);
+  return doc;
+}
+
+function savePeople(doc) {
+  ensure();
+  fs.writeFileSync(PEOPLE, JSON.stringify(doc, null, 2));
+}
+
+function appendRun(row) {
+  ensure();
+  const file = path.join(RUNS, `${new Date().toISOString().slice(0, 10)}.jsonl`);
+  fs.appendFileSync(file, JSON.stringify(row) + "\n");
+  return file;
+}
+
+/** 최근 방문 기록. 파일이 날짜별이라 뒤에서부터 읽는다 */
+function recentRuns(limit = 50) {
+  if (!fs.existsSync(RUNS)) return [];
+  const rows = [];
+  for (const f of fs.readdirSync(RUNS).filter((x) => x.endsWith(".jsonl")).sort().reverse()) {
+    const lines = fs.readFileSync(path.join(RUNS, f), "utf8").trim().split("\n").filter(Boolean).reverse();
+    for (const l of lines) {
+      try {
+        rows.push(JSON.parse(l));
+      } catch {}
+      if (rows.length >= limit) return rows;
+    }
+  }
+  return rows;
+}
+
+module.exports = { DIR, PEOPLE, RUNS, SESSION, SESSIONS, SETTINGS, ACCOUNT_NAME, sessionPath, accounts, setAccountStatus, nextAccount, loadSettings, saveSettings, ensure, loadPeople, savePeople, appendRun, recentRuns };

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@usercase/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1-next.0",
+  "description": "Virtual users that browse your website and tell you what they thought — an MCP server for Claude Code",
+  "license": "UNLICENSED",
+  "homepage": "https://usercase.io",
+  "type": "commonjs",
+  "main": "mcp/server.js",
+  "bin": {
+    "usercase-mcp": "mcp/server.js"
+  },
+  "files": [
+    "mcp/",
+    "src/browser/",
+    "src/persona/",
+    "src/run/",
+    "src/prompts/",
+    "agents/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "node --check mcp/server.js && node scripts/onboarding.js --check && node scripts/agents.js --check",
+    "docs": "node scripts/onboarding.js && node scripts/agents.js",
+    "release:next": "node scripts/release.js next",
+    "release:promote": "node scripts/release.js promote",
+    "release:rollback": "node scripts/release.js rollback",
+    "release:status": "node scripts/release.js status"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "playwright": "^1.58.2",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@google/genai": "^2.23.0"
+  }
+}

package/src/browser/blocked.js

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * 사이트가 우리를 막고 있는가. **오진을 막는 장치다.**
+ *
+ * 고객 사이트 앞에는 보통 Cloudflare·WAF·rate limit 이 있고, 가상 사용자 여럿이 몰리면
+ * 공격으로 읽혀 차단된다. 그때 우리가 "방문 실패" 라고만 보고하면 고객은
+ * **"너희 도구가 안 되네"** 로 읽는다. 실제로는 고객 인프라가 막은 것이고,
+ * 고객이 자기 설정 한 줄로 풀 수 있는 문제다.
+ *
+ * 2026-09-21 에 실제로 겪었다 — 여기어때는 Cloudflare 차단 페이지(응답을 주면서 거부),
+ * 사람인은 연결 리셋(응답 없이 끊음). 두 층이 달라서 신호도 다르다.
+ * 우리 쪽은 멀쩡한데(로컬 SDK 200) 사이트가 끊는 것을 알아채는 데 한참 걸렸다.
+ *
+ * **어느 규칙이 막았는지는 모른다.** 그건 짐작하지 않는다.
+ * "이런 모양으로 막혔고, 이 업체는 보통 이렇게 푼다" 까지만 말한다.
+ *
+ * 의존성 없음. Playwright page 객체만 받는다.
+ */
+
+const { AGENT_HEADER, UA_TAG, KEY_HEADER, KEY_ENV } = require("./card.js");
+
+/** 지시문 안에서 비밀값 자리. 고객이 자기 값으로 바꿔 넣는다 */
+const SECRET = "<your-secret>";
+
+/** 응답 없이 연결이 끊기는 것들. 한 번은 흔하지만 반복되면 사이트가 끊는 것이다 */
+const NET_ERRORS = /ERR_CONNECTION_RESET|ERR_CONNECTION_CLOSED|ERR_CONNECTION_REFUSED|ERR_TIMED_OUT|ERR_EMPTY_RESPONSE|ERR_SOCKET_NOT_CONNECTED/i;
+
+/** 차단 페이지가 스스로 밝히는 글자. 제목과 본문 앞부분에서 찾는다 */
+const BLOCK_TEXT =
+  /you have been blocked|attention required|access denied|forbidden|request blocked|blocked by|security check|are you a robot|unusual traffic|rate limit|too many requests|비정상적인 접근|접근이 차단|잠시 후 다시/i;
+
+/** 응답 헤더로 업체를 가른다. 업체를 알아야 푸는 법을 정확히 말해줄 수 있다 */
+const VENDORS = [
+  { id: "cloudflare", name: "Cloudflare", test: (h) => !!h["cf-ray"] || /cloudflare/i.test(h["server"] || "") },
+  { id: "aws", name: "AWS (CloudFront·WAF)", test: (h) => !!h["x-amz-cf-id"] || /cloudfront/i.test(h["via"] || "") },
+  { id: "akamai", name: "Akamai", test: (h) => !!h["x-akamai-transformed"] || /akamai/i.test(h["server"] || "") },
+  { id: "sucuri", name: "Sucuri", test: (h) => !!h["x-sucuri-id"] },
+  { id: "vercel", name: "Vercel", test: (h) => /vercel/i.test(h["server"] || "") || !!h["x-vercel-id"] },
+];
+
+/**
+ * 업체별로 실제로 하는 일. 규칙 이름은 그 제품 화면의 것을 그대로 쓴다.
+ *
+ * **통과 조건은 `KEY_HEADER` 의 값이다. `AGENT_HEADER` 가 "있으면" 으로 걸면 안 된다** —
+ * 그 헤더는 누구나 넣을 수 있어서, 그렇게 열면 아무 봇이나 그 줄 하나로 WAF 를 지나간다.
+ *
+ * `docs/onboarding.md` 의 업체별 절은 이 목록에서 뽑는다(`npm run docs`). 문서를 손으로 고치지 말 것.
+ */
+const FIXES = {
+  cloudflare: [
+    `Security → WAF → Custom rules → Create rule. Expression: \`any(http.request.headers["${KEY_HEADER.toLowerCase()}"][*] eq "${SECRET}")\` → action Skip, skipping: the remaining Custom rules, Rate limiting rules, Managed rules and Super Bot Fight Mode`,
+    "Bot Fight Mode on the Free plan cannot be skipped by a rule — turn it off while the visits run, or run on staging",
+    "Or allow this computer's IP in Security → WAF → Tools (IP Access Rules)",
+  ],
+  aws: [
+    `Add a rule to the WAF web ACL: header \`${KEY_HEADER.toLowerCase()}\` Exactly matches string \`${SECRET}\` → Allow. Give it a higher priority (lower number) than rate-based and Bot Control rules`,
+    "Or add this computer's IP to an IP set and allow it",
+  ],
+  akamai: [`In Bot Manager, add requests whose \`${KEY_HEADER}\` header equals \`${SECRET}\` to the allowlist`, "Or allow this computer's IP"],
+  sucuri: ["Add this computer's IP to the allowlist in the firewall settings"],
+  vercel: [
+    `Firewall → Custom rules → condition Request Header \`${KEY_HEADER.toLowerCase()}\` Equals \`${SECRET}\` → action Bypass`,
+    "Or turn off Attack Challenge Mode for a while",
+  ],
+  unknown: [
+    `In front of the site (WAF, CDN or reverse proxy), let through requests whose \`${KEY_HEADER}\` header equals \`${SECRET}\``,
+    "Or add this computer's IP to the allowlist",
+  ],
+};
+
+/**
+ * 한 번의 실행 동안 신호를 모은다. 방문마다 새로 만들지 말 것 —
+ * **반복되는지**가 판단의 핵심이라 실행 전체에서 세야 한다.
+ */
+function createBlockWatch({ minNetErrors = 3 } = {}) {
+  const netErrors = [];
+  const blockPages = [];
+  let vendor = null;
+  let lastStatus = null;
+
+  return {
+    /** 페이지에 달아 둔다. 응답·실패를 모두 본다 */
+    watch(page, siteOrigin) {
+      page.on("response", (res) => {
+        let u;
+        try {
+          u = new URL(res.url());
+        } catch {
+          return;
+        }
+        if (u.origin !== siteOrigin) return;
+        const h = res.headers();
+        if (!vendor) {
+          const hit = VENDORS.find((v) => v.test(h));
+          if (hit) vendor = hit;
+        }
+        if (res.status() === 403 || res.status() === 429 || res.status() === 503) lastStatus = res.status();
+      });
+      page.on("requestfailed", (req) => {
+        let u;
+        try {
+          u = new URL(req.url());
+        } catch {
+          return;
+        }
+        if (u.origin !== siteOrigin) return;
+        const err = req.failure()?.errorText || "";
+        if (NET_ERRORS.test(err)) netErrors.push({ at: new Date().toISOString(), err, path: u.pathname });
+      });
+    },
+
+    /** 화면이 차단 페이지인가. 제목과 본문 앞부분만 본다 */
+    notePage({ title = "", text = "", path = "" }) {
+      const head = `${title}\n${text}`.slice(0, 600);
+      if (BLOCK_TEXT.test(head)) {
+        blockPages.push({ at: new Date().toISOString(), path, title: title.slice(0, 120) });
+        return true;
+      }
+      return false;
+    },
+
+    /**
+     * 막혔다고 볼 수 있나. 아니면 null.
+     * 연결 오류 한두 번은 흔하다 — 반복되거나 차단 페이지를 봤을 때만 막혔다고 한다.
+     */
+    verdict() {
+      const enoughNet = netErrors.length >= minNetErrors;
+      if (!enoughNet && blockPages.length === 0) return null;
+      const layer = blockPages.length ? "page" : "network";
+      const v = vendor || { id: "unknown", name: "unknown provider" };
+      const evidence = [];
+      if (blockPages.length) {
+        evidence.push(`Block page ${blockPages.length}× — e.g. "${blockPages[0].title}" (${blockPages[0].path || "/"})`);
+      }
+      if (netErrors.length) {
+        const kinds = [...new Set(netErrors.map((e) => (e.err.match(/ERR_[A-Z_]+/) || [e.err])[0]))];
+        evidence.push(`Connection dropped without a response ${netErrors.length}× — ${kinds.join(", ")}`);
+      }
+      if (lastStatus) evidence.push(`HTTP ${lastStatus} response`);
+      if (vendor) evidence.push(`${vendor.name}, judging by the response headers`);
+      return {
+        blocked: true,
+        layer, // page = 응답을 주면서 거부 · network = 응답 없이 끊음
+        vendor: v.id,
+        vendorName: v.name,
+        evidence,
+        fixes: FIXES[v.id] || FIXES.unknown,
+        counts: { netErrors: netErrors.length, blockPages: blockPages.length },
+      };
+    },
+  };
+}
+
+/** 고객이 그대로 읽을 글. 도구 문제가 아니라는 것부터 말한다 */
+function describeBlock(v, { ua = UA_TAG, keySet = !!process.env[KEY_ENV] } = {}) {
+  if (!v) return null;
+  const L = [];
+  L.push("⚠ The site is blocking the virtual users. This is not a problem with the tool.");
+  L.push("");
+  L.push(v.layer === "page" ? "What happened — the site returns a block page" : "What happened — the site drops the connection without a response");
+  v.evidence.forEach((e) => L.push(`  · ${e}`));
+  L.push("");
+  L.push(`How to fix it (${v.vendorName})`);
+  v.fixes.forEach((f) => L.push(`  · ${f}`));
+  L.push("  · Or run on staging instead of production — it usually has no bot protection");
+  L.push("");
+  // 지시문의 <비밀값> 을 채우려면 먼저 정해야 한다. 안 정했으면 그것부터 말한다
+  L.push(
+    keySet
+      ? `${SECRET} is the value you set in ${KEY_ENV}. It is sent only to this site, in the \`${KEY_HEADER}\` header.`
+      : `${SECRET} is not set yet — put a random value of 16+ characters in ${KEY_ENV}, and the same value in the rule above.`,
+  );
+  L.push("");
+  // GA 같은 브라우저 쪽 도구는 요청 헤더를 못 본다. 헤더로 거르라고 하면 거르려다 실패한다
+  L.push(`To separate virtual-user visits, use the \`${AGENT_HEADER}\` header in logs, and \`${ua}\` in the User-Agent for analytics tools (GA etc.).`);
+  L.push("Analytics tools that run in the browser cannot see request headers.");
+  return L.join("\n");
+}
+
+module.exports = { createBlockWatch, describeBlock, NET_ERRORS, BLOCK_TEXT, VENDORS, FIXES, SECRET };

package/src/browser/card.js

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * 어닝버드 질문 카드를 읽고 답한다. 가상 사용자가 사람처럼 카드를 만나는 자리.
+ *
+ * 화면만 본다 — 페이지 코드를 읽어 "여기 무슨 질문이 걸려 있다" 를 미리 알아내지 않는다.
+ * 카드는 그림자 DOM(#eb-insight) 안에 있고, 방문자에게 보이는 그대로만 본다.
+ *
+ * 의존성 없음. Playwright 의 page/context 객체를 받아서 쓴다.
+ */
+
+/**
+ * 가상 사용자가 HTTP 층에서 자기를 밝히는 헤더. 값은 agent 이름(`qa-explore` 등).
+ *
+ * **고객이 이 헤더로 우리를 다룬다** — 분석 도구에서 빼고, 로그에서 가른다.
+ * WAF 통과는 이것만으로 하면 안 된다 — 누구나 넣을 수 있다. 그건 아래 `KEY_HEADER` 로.
+ * 이름을 바꾸면 고객 설정이 깨진다. 바꿀 거면 `docs/onboarding.md` 를 다시 뽑을 것(`npm run docs`).
+ */
+const AGENT_HEADER = "X-Usercase-Agent";
+
+/**
+ * 브라우저 UA 뒤에 붙이는 꼬리표. 헤더를 안 남기고 UA 만 남기는 로그(nginx 기본 등)에서도
+ * 가상 사용자를 알아볼 수 있게 한다. UA 는 컨텍스트를 만들 때만 정할 수 있어 따로 뺐다.
+ */
+const UA_TAG = "UsercaseQA/1.0";
+const uaWith = (agent, baseUA) => `${baseUA} ${UA_TAG} (${agent})`;
+
+/**
+ * 컨텍스트 옵션에 UA 꼬리표를 붙인다. `base.userAgent` 가 없으면 `defaultUA` 에 붙인다
+ * (보통 Playwright 의 `devices["Desktop Chrome"].userAgent`). 이 파일은 Playwright 를 모르므로 받아 쓴다.
+ *
+ * **모든 방문 컨텍스트에 써야 한다.** 온보딩 문서가 고객에게 "분석 도구에서는 UA 로 가르세요" 라고 하므로,
+ * 꼬리표가 빠진 방문이 하나라도 있으면 그 방문은 고객 전환율에 진짜 방문으로 찍힌다.
+ * (9/21 까지 데스크톱 방문과 링크 수집 방문에 빠져 있었다)
+ */
+const withAgentUA = (agent, base, defaultUA) => ({ ...base, userAgent: uaWith(agent, base.userAgent || defaultUA) });
+
+/**
+ * **위조 대비 비밀값 헤더.** `AGENT_HEADER` 는 누구나 넣을 수 있어서 보안팀이 그것만 보고
+ * WAF 를 열어주지 않는다. 고객이 정한 값을 이 헤더로 보내고, 고객은 WAF 규칙에 같은 값을 넣는다.
+ *
+ * `AGENT_HEADER` 값에 섞지 않고 따로 둔 이유: 에이전트 헤더는 분석 도구·로그에서 가르는 용도라
+ * 여러 곳에 남는다. 비밀값이 거기 섞이면 로그를 보는 사람 누구나 알게 된다.
+ * 또 WAF 규칙은 "값이 정확히 같은가" 가 가장 단순한데, agent 이름이 앞에 붙으면 그게 안 된다.
+ *
+ * **고객 사이트 origin 으로 가는 요청에만 붙인다**(`sendKey`). `setExtraHTTPHeaders` 로 붙이면
+ * 페이지가 부르는 GA·광고·CDN 등 남의 도메인으로 비밀값이 샌다.
+ *
+ * 이름을 바꾸면 고객 WAF 규칙이 깨진다. 바꿀 거면 `docs/onboarding.md` 를 다시 뽑을 것.
+ */
+const KEY_HEADER = "X-Usercase-Key";
+const KEY_ENV = "USERCASE_AGENT_KEY";
+/** 짧으면 추측된다. 32자 무작위를 권하지만 16자 아래만 거절한다 */
+const KEY_MIN = 16;
+
+/** 쓸 비밀값. 인자가 없으면 환경변수. 없으면 null — 비밀값 없이도 돈다(에이전트 헤더만 간다) */
+function agentKey(explicit) {
+  const k = explicit != null ? String(explicit) : process.env[KEY_ENV] || "";
+  if (!k) return null;
+  // 헤더 값에 못 들어가는 글자(공백·한글·제어문자)는 조용히 깨지니 여기서 막는다
+  if (!/^[\x21-\x7e]+$/.test(k)) throw new Error(`${KEY_ENV}: use only ASCII letters, digits and symbols (no spaces)`);
+  if (k.length < KEY_MIN) throw new Error(`${KEY_ENV}: must be at least ${KEY_MIN} characters (now ${k.length})`);
+  return k;
+}
+
+/**
+ * 비밀값을 **고객 사이트 origin 요청에만** 붙인다. key 가 없으면 아무것도 안 한다.
+ *
+ * route 를 쓰면 Playwright 는 그 컨텍스트의 HTTP 캐시를 끈다 — 비밀값을 쓸 때만 드는 비용이다.
+ * `fallback` 이라 다른 route(외부 차단 등)와 겹쳐도 되지만, **다른 route 를 다 건 뒤 마지막에 불러야 한다.**
+ * Playwright 는 나중에 건 route 가 먼저 돈다 — 이걸 먼저 걸면 뒤에 건 route 가 continue() 로 끝내 버려
+ * 비밀값이 한 번도 안 나간다(9/21 driver.js 에서 그랬다).
+ */
+async function sendKey(ctx, siteOrigin, key) {
+  if (!key) return false;
+  if (!siteOrigin) throw new Error(`${KEY_HEADER} is never sent without a site origin — the secret would leak to other domains`);
+  const origin = new URL(siteOrigin).origin;
+  await ctx.route(
+    (u) => u.origin === origin,
+    async (route) => {
+      const headers = { ...(await route.request().allHeaders()), [KEY_HEADER.toLowerCase()]: key };
+      await route.fallback({ headers });
+    },
+  );
+  return true;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * SDK 가 **실제로 돌기 시작했는지** 기다린다. 첫 걸음을 떼기 전에 불러야 한다.
+ *
+ * 광고·트래커가 많은 상용 사이트는 `load` 가 늦게 끝나고 SDK 도 늦게 붙는다
+ * (2026-09-21 사람인: goto 가 60초 타임아웃, 그 뒤에 붙었다).
+ * 그 사이에 봇이 움직이면 **그 조작들이 기록에 안 남는다.**
+ * 방문은 성공한 것처럼 끝나고 기록만 앞부분이 잘려서, 나중에 그 기록으로
+ * "사람들이 이 화면부터 시작하더라" 같은 틀린 결론이 나온다. **조용히 틀리는 종류다.**
+ *
+ * 신호는 sessionStorage 의 `Usercase_bt_session_*.sessionId` 다(이름 바꾸기 전 SDK 는 `Earningbirds_bt_session_*`).
+ * **localStorage 의 visitorId 를 보면 안 된다** — 지난 방문에서 남아 있어서
+ * SDK 가 안 떴는데도 값이 있다. 오늘 그것 때문에 한참 헤맸다.
+ */
+async function waitForSdk(page, { timeoutMs = 20000, everyMs = 250 } = {}) {
+  const started = Date.now();
+  for (;;) {
+    const ok = await page
+      .evaluate(() => {
+        try {
+          for (let i = 0; i < sessionStorage.length; i++) {
+            const k = sessionStorage.key(i);
+            if (!k || !/^(Usercase|Earningbirds)_bt_session_/.test(k)) continue;
+            const v = JSON.parse(sessionStorage.getItem(k) || "null");
+            if (v && v.sessionId) return true;
+          }
+        } catch (e) {}
+        return false;
+      })
+      .catch(() => false);
+    const ms = Date.now() - started;
+    if (ok) return { ready: true, ms };
+    if (ms >= timeoutMs) return { ready: false, ms };
+    await sleep(everyMs);
+  }
+}
+
+/** 지금 화면에 떠 있는 카드. 없으면 null */
+async function readCard(page) {
+  return page
+    .evaluate(() => {
+      const host = document.getElementById("eb-insight");
+      const card = host && host.shadowRoot && host.shadowRoot.querySelector(".eb-ip-card");
+      if (!card || card.classList.contains("eb-ip-leaving")) return null;
+      const q = card.querySelector(".eb-ip-question");
+      return {
+        visible: card.classList.contains("eb-ip-visible"),
+        question: q ? q.textContent.trim() : "",
+        choices: Array.from(card.querySelectorAll(".eb-ip-opt:not(.eb-ip-other):not(.eb-ip-decline)")).map((b) => b.textContent.trim()),
+      };
+    })
+    .catch(() => null);
+}
+
+/** 카드가 뜰 때까지 기다린다. 안 뜨면 null — 안 뜨는 것도 결과다 */
+async function waitCard(page, ms) {
+  for (let t = 0; t < ms; t += 500) {
+    const c = await readCard(page);
+    if (c && c.visible) return c;
+    await sleep(500);
+  }
+  return null;
+}
+
+/**
+ * 카드가 떴을 때 그 사람 화면에 있던 글자. 답할지 무엇을 고를지는 이걸 보고 정한다.
+ * 카드 자신(그림자 DOM)은 innerText 에 안 들어간다.
+ */
+async function screenText(page, max = 6000) {
+  const t = await page.evaluate(() => (document.body ? document.body.innerText : "")).catch(() => "");
+  return t.replace(/[ \t]+/g, " ").replace(/\n{2,}/g, "\n").trim().slice(0, max);
+}
+
+/**
+ * { kind: "choose", index } | { kind: "other", text } | { kind: "close" }
+ * 자유 입력 질문은 선택지가 없어 "other"(자기 말로 쓰기) 아니면 닫기뿐이다.
+ */
+async function answerCard(page, action) {
+  const root = page.locator("#eb-insight .eb-ip-card");
+  if (action.kind === "close") {
+    await root.locator(".eb-ip-close").click({ timeout: 5000 });
+  } else if (action.kind === "choose") {
+    await root.locator(".eb-ip-opt:not(.eb-ip-other)").nth(action.index).click({ timeout: 5000 });
+  } else {
+    // 선택지가 있는 카드는 "기타" 를 눌러야 입력칸이 나온다. 자유 입력 카드는 이미 나와 있다
+    const other = root.locator(".eb-ip-other");
+    if (await other.count()) await other.click({ timeout: 5000 });
+    await root.locator(".eb-ip-input").fill(action.text, { timeout: 5000 });
+    await root.locator(".eb-ip-input").press("Enter");
+  }
+  await sleep(2000);
+}
+
+/**
+ * 이 방문이 사람이 아니라 가상 사용자임을 밝힌다. SDK 가 이 이름을 응답에 실어 보내고
+ * 서버가 진짜 방문자 답과 갈라 센다. **이 표시를 빼면 안 된다.**
+ *
+ * hideDevOverlay: 로컬 개발 서버에서만. Next.js 개발 오버레이가 화면 귀퉁이를 덮어 탭을 가로챈다.
+ * 진짜 방문자에게는 없는 층이라 가상 사용자 방문에서만 숨긴다.
+ *
+ * siteOrigin·key: 위조 대비 비밀값(`KEY_HEADER`). key 를 안 주면 환경변수 `USERCASE_AGENT_KEY`.
+ * 비밀값이 있으면 siteOrigin 이 반드시 있어야 한다 — 그 origin 에만 보낸다.
+ */
+async function markAgent(ctx, agent, { debugCards = true, hideDevOverlay = true, persona = null, siteOrigin = null, key } = {}) {
+  /**
+   * **HTTP 층에서도 밝힌다.** 아래 `window.Earningbirds.agent` 는 페이지 JS 안이라 우리 SDK 만 읽는다.
+   * 고객의 WAF·CDN·분석 도구는 페이지 앞에 앉아 헤더만 보므로 그것만으로는 우릴 알아볼 수 없다.
+   *
+   * 그러면 가상 사용자 방문이 **공격으로 보여 차단되고**(2026-09-21 여기어때 Cloudflare 차단·사람인 연결 리셋),
+   * 막히지 않아도 **고객의 분석·A/B 테스트에 실제 방문으로 섞인다.** 둘 다 헤더 한 줄이면 고객이 가를 수 있다.
+   *
+   * 개발 환경에서만 보내면 안 된다 — 막는 것도 분석이 오염되는 것도 운영에서 일어난다.
+   * 운영에서 빼면 다시 "사람인 척하는 봇" 이 되고, 그게 막히는 이유다.
+   */
+  await ctx.setExtraHTTPHeaders({ [AGENT_HEADER]: agent });
+  // 비밀값은 고객이 정했을 때만. 정했는데 siteOrigin 을 안 주면 sendKey 가 멈춘다 — 새는 것보다 낫다
+  await sendKey(ctx, siteOrigin, agentKey(key));
+  await ctx.addInitScript(
+    ({ name, debugCards: dbg, hideDevOverlay: hide, persona: who }) => {
+      if (dbg) {
+        try {
+          localStorage.setItem("Usercase_ip_debug", "1");
+          localStorage.setItem("Earningbirds_ip_debug", "1"); // 이름 바꾸기 전 SDK
+        } catch (e) {}
+      }
+      try {
+        // 새 SDK 는 window.Usercase, 이름 바꾸기 전 SDK 는 window.Earningbirds 를 읽는다 — 둘 다 이 한 객체를 보게 둔다
+        window.Usercase = window.Earningbirds = window.Usercase || window.Earningbirds || {};
+        window.Usercase.agent = name;
+        // 이 방문이 누구였는지. 닫고 나가도 남아야 해서 노출 때 같이 간다
+        if (who) window.Usercase.agentPersona = who;
+      } catch (e) {}
+      if (hide) {
+        try {
+          document.addEventListener("DOMContentLoaded", () => {
+            const st = document.createElement("style");
+            st.textContent = "nextjs-portal{display:none !important}";
+            document.head.appendChild(st);
+          });
+          // 개발 오류 창은 열리면서 페이지 스크롤을 잠근다(body overflow hidden). 창을 숨겨도 잠금이 남아
+          // 데스크톱에서 굴려도 안 내려갔다(10/13 bluetags). 그 창이 떠 있을 때만 잠금을 푼다
+          setInterval(() => {
+            const p = document.querySelector("nextjs-portal");
+            const open = p && p.shadowRoot && p.shadowRoot.querySelector("[data-nextjs-dialog],[data-nextjs-dialog-overlay]");
+            if (open && document.body && document.body.style.overflow === "hidden") document.body.style.overflow = "";
+          }, 500);
+        } catch (e) {}
+      }
+    },
+    { name: agent, debugCards, hideDevOverlay, persona },
+  );
+}
+
+/** 방금 그렇게 한 이유. 답하거나 닫기 **직전에** 넣는다 — SDK 가 보낼 때 읽는다 */
+async function noteReason(page, reason) {
+  await page
+    .evaluate((r) => {
+      window.Usercase = window.Earningbirds = window.Usercase || window.Earningbirds || {};
+      window.Usercase.agentNote = r;
+    }, String(reason || "").slice(0, 1000))
+    .catch(() => {});
+}
+
+module.exports = {
+  sleep,
+  readCard,
+  waitCard,
+  screenText,
+  answerCard,
+  markAgent,
+  noteReason,
+  waitForSdk,
+  AGENT_HEADER,
+  UA_TAG,
+  uaWith,
+  withAgentUA,
+  KEY_HEADER,
+  KEY_ENV,
+  KEY_MIN,
+  agentKey,
+  sendKey,
+};