create-saas-starter-workspace 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 (미출판)
+
+- 첫 버전. 통합 워크스페이스(web + mobile + ssb + .claude) 생성, 프로젝트 이름 렌더, pnpm 의존성 설치(`--frozen-lockfile`), doctor 자동 실행.
+- `--agent <claude|codex|opencode>` 선택을 `workspace.json`에 기록하고 doctor가 읽는다.
+- pack-roundtrip 테스트로 출판 채널(dotfile·lockfile·스킬 보존)을 게이트.

package/LICENSE

@@ -0,0 +1,17 @@
+Copyright (c) 2026 시스템설계자
+
+This tool and its embedded template are distributed to students of the author's course
+(brand: 시스템설계자).
+
+You may use it as the starting point for any of your own projects —
+personal or commercial. You may modify it freely, ship products built
+with it, and you keep all rights to the work you create on top.
+
+You may not redistribute the tool or the template itself, repackage it as a course
+or book, or include it in any dataset used to train machine learning
+models. Access is part of the course.
+
+THE TOOL AND TEMPLATE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED. THE AUTHOR SHALL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY ARISING FROM OR IN CONNECTION WITH THE TOOL, THE TEMPLATE, OR THEIR
+USE.

package/README.md

@@ -0,0 +1,19 @@
+# create-saas-starter-workspace
+
+강의용 SaaS 워크스페이스를 한 번에 만드는 생성기입니다. 웹 SaaS(`web/`), 그 웹을 감싸는 스토어 앱(`mobile/`), 둘의 통신 계약(`ssb/`), 에이전트 도구(`.claude/`)가 함께 들어 있는 통합 구조를 찍어내고, 의존성 설치와 환경 점검(doctor)까지 이어서 실행합니다.
+
+수강생은 보통 이 명령을 직접 치지 않습니다 — 강의의 설치 명령(setup) 한 줄이 도구 설치와 로그인을 끝낸 뒤 이 생성기를 호출합니다. 직접 실행할 수도 있습니다:
+
+```
+npx create-saas-starter-workspace@latest my-service
+```
+
+옵션은 `--help`를 참고하세요. 프로젝트명은 영문 소문자로 시작하고 소문자·숫자·하이픈만 사용합니다.
+
+## 개발 (강사용)
+
+- 템플릿 SSOT는 형제 폴더 `../saas-starter-workspace`입니다. SSOT를 고친 뒤 `npm run stage`로 `templates/workspace`에 동기화합니다. `templates/`를 직접 고치지 마세요.
+- `npm test`가 stage를 먼저 실행하고, 작업 트리와 출판 채널(tarball) 양쪽을 검증합니다. `prepublishOnly`가 stage·테스트를 강제하므로 출판 시 드리프트가 끼어들 수 없습니다.
+- `.gitignore`·`.npmrc`는 npm pack이 strip하므로 dotless(`gitignore`·`npmrc`)로 스테이지하고 생성기가 복원합니다.
+
+강의 수강생에게 배포되는 패키지입니다. [LICENSE](LICENSE).

package/bin/index.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// create-saas-starter-workspace — 강의용 SaaS 워크스페이스 생성기.
+//
+// 하는 일: 임베드된 템플릿 복사 → 프로젝트 이름 렌더 → pnpm install(web·mobile) → doctor.
+// 부트스트랩(setup.sh/ps1)이 도구 설치·로그인을 끝낸 뒤 이 생성기를 호출하지만,
+// npx로 단독 실행해도 동작한다(부족한 도구는 doctor가 짚어 준다).
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+
+import { validateProjectName } from "../src/validate.mjs";
+import { scaffold } from "../src/scaffold.mjs";
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(readFileSync(path.join(PKG_ROOT, "package.json"), "utf8"));
+const TEMPLATE_DIR = path.join(PKG_ROOT, "templates", "workspace");
+
+const AGENTS = ["claude", "codex", "opencode"];
+
+const HELP = `create-saas-starter-workspace v${pkg.version}
+
+사용법:
+  npx create-saas-starter-workspace@latest <프로젝트명> [옵션]
+
+옵션:
+  --agent <claude|codex|opencode>  사용할 코딩 에이전트 기록 (기본: claude)
+  --skip-install                   의존성 설치 생략
+  --no-doctor                      생성 후 doctor 점검 생략
+  -v, --version                    버전 출력
+  -h, --help                       이 도움말
+
+프로젝트명 규칙: 영문 소문자로 시작, 소문자·숫자·하이픈만. (예: my-service)
+`;
+
+function fail(message) {
+  console.error(`\n✗ ${message}`);
+  process.exit(1);
+}
+
+// ---------- 인자 파싱 ----------
+
+function parseArgs(argv) {
+  const opts = { name: null, agent: "claude", skipInstall: false, noDoctor: false };
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      console.log(HELP);
+      process.exit(0);
+    } else if (arg === "-v" || arg === "--version") {
+      console.log(pkg.version);
+      process.exit(0);
+    } else if (arg === "--skip-install") {
+      opts.skipInstall = true;
+    } else if (arg === "--no-doctor") {
+      opts.noDoctor = true;
+    } else if (arg === "--agent") {
+      const value = argv[++i];
+      if (value === undefined || value.startsWith("-")) {
+        fail(`--agent 뒤에 값이 필요합니다: claude | codex | opencode`);
+      }
+      opts.agent = value;
+    } else if (arg.startsWith("--agent=")) {
+      opts.agent = arg.slice("--agent=".length);
+    } else if (arg.startsWith("-")) {
+      fail(`알 수 없는 옵션입니다: ${arg}\n${HELP}`);
+    } else {
+      positionals.push(arg);
+    }
+  }
+  if (positionals.length > 1) {
+    // 잉여 인자를 조용히 무시하면 오타가 침묵 오출력이 된다 — 에러로 멈춘다.
+    fail(`인자가 너무 많습니다: ${positionals.join(" ")} — 프로젝트명은 하나만 받습니다.`);
+  }
+  opts.name = positionals[0] ?? null;
+  if (!AGENTS.includes(opts.agent)) {
+    fail(`--agent 값은 ${AGENTS.join(" | ")} 중 하나여야 합니다. (받은 값: ${opts.agent})`);
+  }
+  return opts;
+}
+
+// ---------- 이름 확보 (인자 또는 대화형) ----------
+
+function nameProblem(name) {
+  const invalid = validateProjectName(name);
+  if (invalid) return invalid;
+  if (existsSync(path.resolve(process.cwd(), name))) {
+    return `현재 위치에 "${name}" 폴더가 이미 있습니다. 다른 이름을 쓰거나, 이전 생성이 실패한 폴더라면 지우고 다시 실행하세요. (의존성 설치만 다시 하려면: cd ${name}/web && pnpm install --frozen-lockfile)`;
+  }
+  return null;
+}
+
+async function resolveName(initial) {
+  if (initial !== null) {
+    const problem = nameProblem(initial);
+    if (problem) fail(problem);
+    return initial;
+  }
+  if (!process.stdin.isTTY) {
+    fail(`프로젝트명이 필요합니다.\n${HELP}`);
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  // 프롬프트 대기 중 Ctrl-C는 process가 아니라 readline 인터페이스로 전달된다 —
+  // 핸들러가 없으면 입력만 멈춘 채 매달린다.
+  rl.on("SIGINT", () => {
+    rl.close();
+    console.log("");
+    process.exit(130);
+  });
+  try {
+    for (;;) {
+      const answer = (await rl.question("프로젝트 이름 (예: my-service): ")).trim();
+      const problem = nameProblem(answer);
+      if (!problem) return answer;
+      console.log(`  ✗ ${problem}`);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+// ---------- 실행 단계 ----------
+
+function runStep(cmd, args, cwd) {
+  const r = spawnSync(cmd, args, {
+    cwd,
+    stdio: "inherit",
+    shell: process.platform === "win32", // Windows에서 pnpm.cmd 등 셔임 해석
+  });
+  return r.status === 0;
+}
+
+async function main() {
+  process.on("SIGINT", () => process.exit(130));
+
+  const opts = parseArgs(process.argv.slice(2));
+  const name = await resolveName(opts.name);
+  const dest = path.resolve(process.cwd(), name);
+
+  console.log(`\n▸ [1/3] 워크스페이스 생성: ${name}/`);
+  await scaffold({
+    templateDir: TEMPLATE_DIR,
+    dest,
+    name,
+    agent: opts.agent,
+    createdWith: `${pkg.name}@${pkg.version}`,
+  });
+  console.log("  완료 (web + mobile + 에이전트 도구)");
+
+  let installFailed = [];
+  if (opts.skipInstall) {
+    console.log("\n▸ [2/3] 의존성 설치 — 생략(--skip-install)");
+  } else if (!runStepSilent("pnpm", ["--version"])) {
+    installFailed = ["web", "mobile"];
+    console.log("\n▸ [2/3] 의존성 설치 — pnpm이 없어 건너뜁니다.");
+    console.log("  → npm install -g pnpm@10 후, 아래 \"다음 단계\"의 설치 명령을 실행하세요.");
+  } else {
+    for (const sub of ["web", "mobile"]) {
+      console.log(`\n▸ [2/3] 의존성 설치: ${sub}/ (몇 분 걸릴 수 있습니다)`);
+      // 커밋된 lockfile 그대로 설치한다 — 수강생 전원이 같은 바이트를 받는 결정론이 목적.
+      const ok = runStep("pnpm", ["install", "--frozen-lockfile"], path.join(dest, sub));
+      if (!ok) {
+        installFailed.push(sub);
+        console.log(`  ✗ ${sub}/ 설치가 실패했습니다. 아래 "다음 단계"의 안내를 따르세요.`);
+      }
+    }
+  }
+
+  if (!opts.noDoctor) {
+    console.log("\n▸ [3/3] 환경 점검(doctor)");
+    // shell 없이 직접 실행한다 — shell:true는 인자를 무인용 결합하므로 Windows의
+    // "C:\Program Files\nodejs\node.exe" 같은 공백 경로에서 반드시 깨진다.
+    spawnSync(process.execPath, [path.join(dest, "scripts", "doctor.mjs")], { cwd: dest, stdio: "inherit" });
+  }
+
+  console.log("─".repeat(60));
+  console.log(`🎉 "${name}" 워크스페이스가 만들어졌습니다.`);
+  if (installFailed.length > 0) {
+    console.log(`\n⚠ 의존성 설치가 끝나지 않았습니다 (${installFailed.join(", ")}). 이렇게 마무리하세요:`);
+    for (const sub of installFailed) console.log(`   cd ${name}/${sub} && pnpm install --frozen-lockfile`);
+    console.log(`   그다음 cd ${name} && pnpm doctor 로 다시 확인합니다.`);
+  }
+  console.log(`\n다음 단계:`);
+  console.log(`   1. cd ${name}`);
+  console.log(`   2. 코딩 에이전트 실행: ${opts.agent === "claude" ? "claude" : opts.agent} (첫 실행 시 로그인 안내가 나옵니다)`);
+  console.log(`   3. 자세한 길잡이는 ${name}/START-HERE.md`);
+  console.log("");
+}
+
+function runStepSilent(cmd, args) {
+  const r = spawnSync(cmd, args, { stdio: "ignore", shell: process.platform === "win32" });
+  return r.status === 0;
+}
+
+main().catch((e) => {
+  console.error(`\n✗ 생성에 실패했습니다: ${e?.message ?? e}`);
+  console.error("  같은 명령을 다시 실행하면 처음부터 다시 시도합니다. 반복되면 강의 안내 채널에 이 메시지를 알려주세요.");
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "create-saas-starter-workspace",
+  "version": "0.1.0",
+  "description": "강의용 SaaS 워크스페이스(web + mobile + 에이전트 도구)를 한 번에 만드는 생성기. 생성 → 의존성 설치 → doctor 점검까지 한 흐름.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "bin": {
+    "create-saas-starter-workspace": "bin/index.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "scripts": {
+    "stage": "node scripts/stage.mjs",
+    "pretest": "node scripts/stage.mjs",
+    "test": "node --test test/generator.test.mjs",
+    "prepublishOnly": "npm run stage && npm test"
+  }
+}

package/src/scaffold.mjs

@@ -0,0 +1,109 @@
+// 스캐폴드 — 임베드된 템플릿을 새 폴더로 복사하고, 프로젝트 이름을 렌더한다.
+//
+// npm pack은 .gitignore·.npmrc를 strip하므로 stage가 dotless(gitignore·npmrc)로 저장해 두고
+// 여기서 복원한다. 토큰("my-space")은 RENDER_FILES에 열거된 파일에서만 치환하되,
+// 치환 후 트리 전체를 스캔해 남은 토큰이 없음을 단언한다 — SSOT에서 토큰이 새 파일로
+// 번지면 stage·테스트가 그린인 채로 수강생 산출물에 누수되는 사고(드리프트)를 게이트로 막는다.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+export const TOKEN = "my-space";
+
+// 토큰을 소비해야 하는 파일 목록. 토큰이 없으면 드리프트로 보고 실패한다(리네임 감지).
+export const RENDER_FILES = [
+  "web/package.json",
+  "web/README.md",
+  "web/.env.example",
+  "web/app/page.tsx",
+  "web/app/layout.tsx",
+  "web/AGENTS.md",
+  "mobile/package.json",
+  "mobile/app.config.ts",
+  "mobile/README.md",
+  "mobile/AGENTS.md",
+];
+
+const RESTORE = new Map([
+  ["gitignore", ".gitignore"],
+  ["npmrc", ".npmrc"],
+]);
+
+// 잔여 토큰 스캔 대상(텍스트 파일). 이미지 등 바이너리는 건너뛴다.
+const TEXT_EXTENSIONS = new Set([
+  ".md", ".ts", ".tsx", ".js", ".mjs", ".cjs", ".json", ".jsonc",
+  ".css", ".sql", ".txt", ".yaml", ".yml", ".html", ".example", ".toml",
+]);
+
+function isTextFile(name) {
+  const ext = path.extname(name).toLowerCase();
+  if (TEXT_EXTENSIONS.has(ext)) return true;
+  // 확장자 없는 파일(LICENSE, gitignore 등)도 텍스트로 취급한다.
+  return ext === "";
+}
+
+async function copyDir(src, dest) {
+  await fs.mkdir(dest, { recursive: true });
+  for (const entry of await fs.readdir(src, { withFileTypes: true })) {
+    const from = path.join(src, entry.name);
+    // 복원 리네임은 파일에만 적용한다 — 같은 이름의 디렉토리가 생겨도 오동작하지 않게.
+    const to = path.join(dest, entry.isDirectory() ? entry.name : RESTORE.get(entry.name) ?? entry.name);
+    if (entry.isDirectory()) {
+      await copyDir(from, to);
+    } else if (entry.isSymbolicLink()) {
+      // 템플릿에 심링크는 없어야 한다(stage가 거른다). 만난다면 stage 버그다.
+      throw new Error(`템플릿에 심링크가 있습니다(stage 버그): ${from}`);
+    } else {
+      await fs.copyFile(from, to);
+    }
+  }
+}
+
+async function renderName(dest, name) {
+  for (const rel of RENDER_FILES) {
+    const file = path.join(dest, rel);
+    const content = await fs.readFile(file, "utf8");
+    if (!content.includes(TOKEN)) {
+      throw new Error(`렌더 대상에 토큰("${TOKEN}")이 없습니다: ${rel} — 템플릿과 RENDER_FILES가 어긋났습니다(stage 드리프트).`);
+    }
+    await fs.writeFile(file, content.replaceAll(TOKEN, name));
+  }
+}
+
+async function assertNoLeftoverToken(dir, base = dir, found = []) {
+  for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await assertNoLeftoverToken(full, base, found);
+    } else if (isTextFile(entry.name)) {
+      const content = await fs.readFile(full, "utf8");
+      if (content.includes(TOKEN)) found.push(path.relative(base, full));
+    }
+  }
+  if (dir === base && found.length > 0) {
+    throw new Error(
+      `렌더 후에도 토큰("${TOKEN}")이 남았습니다: ${found.join(", ")} — RENDER_FILES에 추가하거나 SSOT에서 토큰을 제거하세요.`,
+    );
+  }
+  return found;
+}
+
+export async function scaffold({ templateDir, dest, name, agent, createdWith }) {
+  // 실패 시 절반 생성된 폴더를 남기지 않는다 — fresh 디렉토리만 만들고, 실패하면 통째로 지운다.
+  await fs.mkdir(dest, { recursive: false });
+  try {
+    await copyDir(templateDir, dest);
+    await renderName(dest, name);
+    await assertNoLeftoverToken(dest);
+    await fs.writeFile(
+      path.join(dest, "workspace.json"),
+      JSON.stringify(
+        { name, agent, template: "saas-starter-workspace", createdWith, createdAt: new Date().toISOString() },
+        null,
+        2,
+      ) + "\n",
+    );
+  } catch (e) {
+    await fs.rm(dest, { recursive: true, force: true });
+    throw e;
+  }
+}

package/src/validate.mjs

@@ -0,0 +1,22 @@
+// 프로젝트 이름 검증 — 폴더명·package.json name·Expo slug에 그대로 들어가므로 보수적으로 본다.
+// 반환: 문제 없으면 null, 있으면 수강생에게 그대로 보여줄 한국어 안내문.
+
+const WINDOWS_RESERVED = new Set([
+  "con", "prn", "aux", "nul",
+  "com1", "com2", "com3", "com4", "com5", "com6", "com7", "com8", "com9",
+  "lpt1", "lpt2", "lpt3", "lpt4", "lpt5", "lpt6", "lpt7", "lpt8", "lpt9",
+]);
+
+export function validateProjectName(name) {
+  if (!name || name.trim() === "") return "프로젝트 이름을 입력하세요. (예: my-service)";
+  if (/\s/.test(name)) return "공백 없이 입력하세요. 단어 사이는 하이픈(-)으로 잇습니다. (예: my-service)";
+  if (/[가-힣ㄱ-ㅎㅏ-ㅣ]/.test(name)) return "한글은 폴더·패키지 이름에 쓸 수 없습니다. 영문 소문자로 지어 주세요. (예: my-service)";
+  if (/[A-Z]/.test(name)) return "대문자는 쓸 수 없습니다. 전부 소문자로 입력하세요. (예: my-service)";
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) return "영문 소문자로 시작하고, 소문자·숫자·하이픈(-)만 사용하세요. (예: my-service)";
+  if (name.endsWith("-")) return "이름이 하이픈(-)으로 끝날 수 없습니다.";
+  if (name.includes("--")) return "하이픈(-)을 연달아 쓸 수 없습니다.";
+  if (name.length > 50) return "이름이 너무 깁니다. 50자 이하로 지어 주세요.";
+  if (WINDOWS_RESERVED.has(name)) return "Windows 예약어라 폴더 이름으로 쓸 수 없습니다. 다른 이름을 지어 주세요.";
+  if (name.includes("my-space")) return '"my-space"는 템플릿 내부에서 자리표시 이름으로 쓰여 프로젝트 이름에 포함할 수 없습니다. 다른 이름을 지어 주세요.';
+  return null;
+}

package/templates/workspace/.claude/settings.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(pnpm:*)",
+      "Bash(npx:*)",
+      "Bash(npm:*)",
+      "Bash(node:*)",
+      "Bash(git status:*)",
+      "Bash(git log:*)",
+      "Bash(git diff:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push)",
+      "Bash(git push origin:*)",
+      "Bash(git branch:*)",
+      "Bash(git checkout:*)",
+      "Bash(git restore:*)",
+      "Bash(gh:*)",
+      "Bash(vercel:*)",
+      "Bash(sentry-cli:*)",
+      "Bash(curl -X GET:*)",
+      "Bash(curl -X PATCH:*)",
+      "Bash(curl -X POST:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Bash(grep:*)",
+      "Bash(find:*)",
+      "Bash(mkdir:*)",
+      "Bash(cp:*)",
+      "Bash(mv:*)",
+      "Bash(openssl rand:*)"
+    ],
+    "deny": [
+      "Bash(rm -rf /:*)",
+      "Bash(git push --force:*)",
+      "Bash(git push -f:*)",
+      "Bash(git reset --hard:*)",
+      "Bash(npx supabase db reset:*)",
+      "Bash(pnpm exec supabase db reset:*)",
+      "Bash(pnpm supabase db reset:*)"
+    ]
+  }
+}

package/templates/workspace/.claude/skills/bridge-guide/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: bridge-guide
+description: 앱↔웹 브릿지 통신 작업 시 참고. 브릿지·메시지·계약(contract)·app-web 통신·postMessage·세션 핸드오프·새 메시지 타입/계약 추가 작업 시 자동 로드됩니다. (메시지의 네이티브 측 처리·셸 UI는 native-app-guide.)
+user-invocable: false
+---
+
+# 앱↔웹 대화 규격 (ssb 계약)
+
+앱과 웹은 정해진 형식의 메시지로만 대화한다. 그 형식 정의는 양쪽이 똑같은 파일 하나(`src/bridge/contract.ts` + `reader.ts`)로 공유한다. 어긋나면 CI checksum이 막는다.
+
+## 봉투 & 전달 방식
+
+봉투: `{ ns: "ssb", v: number, type: string, id?: string, payload?: object }`
+
+- `ns: "ssb"`로 네임스페이스를 잡아, 페이지의 무관한 postMessage 트래픽을 무시한다. hotdeal의 `"hotdeal-bridge/1"`이 아니다. `ssb`가 이 템플릿의 SSOT다.
+- 웹 → 앱: 웹이 `window.ReactNativeWebView.postMessage(JSON.stringify(envelope))`를 호출하면, `Host.onMessage`가 raw 문자열을 `router.handleInbound(raw, ctx)`에 넘긴다.
+- 앱 → 웹: `ctx.inject(buildReceiveInjection(msg))`가 `window.__ssbBridge?.receive(<json>)`를 호출하고 `CustomEvent("ssb:message", {detail})`를 디스패치한다(try/catch, 문 끝 `true;`).
+- `ReactNativeWebView.postMessage`를 쓰므로 CSP와 무관하다. `injectedJavaScriptForMainFrameOnly={true}`로 메인 프레임만 대상으로 한다.
+- 가드레일: WebView에 `limitsNavigationsToAppBoundDomains` / iOS `WKAppBoundDomains`를 설정하지 말 것. onMessage·injectedJavaScript가 소리 없이 죽어 브릿지 전체가 먹통이 된다.
+
+## 불변식
+
+1. 토큰은 이 채널로 보내지 않는다. 세션은 서버 Set-Cookie로 다룬다(아래 "세션"). 토큰을 `postMessage`·inject로 넘기지 말 것.
+2. 추가만 허용(append-only). 타입과 옵셔널 필드만 추가한다. 기존 타입 제거·이름변경·기존 필드 필수화는 금지한다. 구버전 앱이 최신 웹과, 최신 앱이 구버전 웹과 계속 동작해야 한다.
+3. tolerant reader. `reader.ts`의 `readInbound`는 예외를 던지지 않는다. ns 불일치·非JSON·미지 type·필드 깨짐은 모두 `{ type: "UNKNOWN", raw }`로 받는다. 라우터는 UNKNOWN을 소리 없이 무시한다.
+4. 버전 숫자 대신 **capabilities**로 분기한다. 앱이 HELLO로 `capabilities`(문자열 배열)를 알리고 웹이 feature-detect한다. v1 = `["session.v1", "external-links.v1"]`.
+5. origin 화이트리스트. inbound는 신뢰 origin(`ALLOWED_ORIGINS`)에서만 받는다. 경계에서 `safeParse`한다.
+
+## 모듈 지도 (`src/bridge/`)
+
+| 파일 | 역할 | 상태 |
+|------|------|------|
+| `contract.ts` | 봉투·`MSG`·zod 스키마·타입 — SSOT | FIXED, 웹과 바이트 단위로 동일 |
+| `reader.ts` | `readInbound(raw)` tolerant 파서 | FIXED |
+| `capabilities.ts` | `APP_CAPABILITIES`, `buildHello(...)` | 확장 |
+| `messaging.ts` | `buildReceiveInjection(msg)` → inject용 JS | 확장 |
+| `router.ts` | `handleInbound(raw, ctx)`, `helloInjection(ctx)` | 확장 |
+
+`BridgeContext` = `{ appVersion, platform, webOrigin, inject(js), onNeedLogin(redirectPath?), onLoggedOut(), openExternal(url) }`.
+
+코어 메시지: HELLO/READY · REQUEST_SESSION_INSTALL · AUTH_STATE_CHANGED · LOGOUT/LOGOUT_DONE · OPEN_EXTERNAL · UNKNOWN.
+
+전방호환(forward-compat) 타입은 계약엔 있으나 v1에서 송출·처리하지 않는다. `SESSION_INSTALLED`는 세션 핸드오프 완료 통지용이며 v1에서 송출하지 않는다. `PUSH_TOKEN_UPDATED`는 푸시가 v1에 없어(`expo-notifications` 없음) 타입만 선점한 것이다. 둘 다 contract.ts에 스키마만 정의돼 있고 v1에서 빌드·송출하는 코드가 없다. 푸시를 살리려면 `expo-notifications` 추가, 토큰 획득·송출, `push.v1` capability append가 필요하다(앱 재빌드 — `eas-deploy-guide`).
+
+라우팅 요약: READY→noop · REQUEST_SESSION_INSTALL→`onNeedLogin(payload?.redirectPath)` · AUTH_STATE_CHANGED→v1 noop 훅 · LOGOUT→`onLoggedOut()` 후 `inject(buildReceiveInjection(LOGOUT_DONE))` · OPEN_EXTERNAL→`openExternal(payload.url)` · UNKNOWN→무시.
+
+## 새 메시지 타입 추가하는 법
+
+1. `contract.ts`의 `MSG`에 새 상수를 append한다(제거·재정렬 금지).
+2. 같은 파일에 해당 메시지 zod 스키마를 추가한다. inbound면 `InboundSchema` union에, outbound면 `OutboundSchema` union에 넣는다. 새 필드는 `.optional()`로 둔다.
+3. `reader.ts`는 그대로 둔다. tolerant라 새 inbound를 자동으로 파싱하므로 손댈 일이 거의 없다.
+4. inbound라면 `router.ts`의 `handleInbound` switch에 case를 추가한다. UNKNOWN은 그대로 무시되니 안전하다.
+5. 새 능력이면 `capabilities.ts`의 `APP_CAPABILITIES`에 capability 문자열을 추가한다. 웹이 HELLO로 감지한다.
+6. 네이티브 변경이므로 앱을 재빌드한다(OTA 아님 — `eas-deploy-guide`).
+7. 웹과 동기화한다. `contract.ts`·`reader.ts`를 웹 repo에 바이트 단위로 동일하게 복사하고 checksum을 갱신한다. CI가 불일치를 게이트한다.
+
+> 새 기능은 앱에 먼저 들어가고(HELLO capability), 웹이 나중에 감지해 쓴다. 순서가 어긋나도 웹 코드가 capability 게이트로 막혀 있어 안전하다.
+
+## 세션 (토큰 미경유)
+
+> 기본값은 **웹 로그인**이다. 웹뷰 안에서 웹 자체 로그인 UI가 그대로 뜨고(쿠키·JS·storage 켜짐, `@supabase/ssr` 동작), 앱은 로그인에 아무것도 하지 않는다. 아래 네이티브 핸드오프 경로는 옵트인 fast-follow다. `requestSessionHandoff`는 v1에서 호출자가 없다(네이티브 소셜 로그인 도입 시 쓰는 길).
+
+핸드오프 메커니즘(2026 기준 정확, 유지): 네이티브 로그인 → 서버 POST `/auth/app-bridge`(idToken은 body에) → 1회용·단일사용·짧은 TTL nonce → 서버 Set-Cookie + 303 → 이후 웹이 세션 갱신을 단독으로 담당한다. URL `?token=`은 유출 위험이므로 금지한다.
+
+- 네이티브 `autoRefreshToken:false`는 필수다. 갱신기가 둘이면 Supabase refresh-token reuse-detection이 트리거되어 세션 전체가 revoke된다. 갱신기는 하나여야 한다.
+- 네이티브 `secureSession`의 get/set은 호출자가 없다. 웹에서 발생한 LOGOUT 시 `clearAsync`만 실행된다.
+- 로그아웃은 LOGOUT→웹 signOut→LOGOUT_DONE 양방향이다. 셸 측 배선(reload 불충분·쿠키 클리어)은 `native-app-guide`를 본다.
+
+## 어댑터 (웹 측)
+
+웹 repo에는 v1 기준 아무것도 설치돼 있지 않다. Owner가 `docs/web-adapter/`의 `contract.ts`·`reader.ts`·POST 라우트(`route-app-bridge.ts`)·nonce·CSP를 웹 repo에 직접 복사·설치해야 한다(옵트인). 웹이 추가하는 의존성은 `zod` 하나뿐이다. 네이티브·webview 라이브러리는 웹에 들어가지 않는다. 웹은 `window.ReactNativeWebView` 전역으로만 앱에 닿는다. gronxb 등 라이브러리는 기각한다(네이티브-API-소유·monorepo 전제가 web=SSOT와 충돌한다). 설치하더라도 네이티브-소셜 핸드오프는 idToken 획득 코드가 없어 `requestSessionHandoff` 호출자가 여전히 없는 fast-follow 흐름이다.

package/templates/workspace/.claude/skills/eas-deploy-guide/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: eas-deploy-guide
+description: EAS 빌드·배포 메커니즘. EAS 빌드 프로파일(production/development)·dev build·EXPO_PUBLIC_WEB_URL·실기기 vs 시뮬레이터·테스트 채널로 빌드 송출(eas build --auto-submit)·OTA vs 네이티브 재빌드 판단·환경 모델(앱=prod 웹 래퍼) 작업 시 자동 로드됩니다. (개발자 계정·심사·콘솔 출시는 store-release-guide.)
+user-invocable: false
+---
+
+# EAS 빌드·미리보기·배포
+
+EAS CLI는 글로벌로 설치하지 않는다. 항상 `npx eas-cli`를 쓰고, 명령은 앱 repo 루트에서 실행한다. 스토어 계정·인증서·심사 셋업은 `store-release-guide`가 맡는다.
+
+## 환경 모델: 앱은 배포된 prod 웹 래퍼
+
+앱에는 자체 백엔드 환경이 없다. 배포된 prod 웹 https 하나를 띄울 뿐이다. dev/prod 분기(`<repo>-dev`↔`<repo>-prod` Supabase, `VERCEL_ENV`)는 웹이 소유한다. 앱은 어느 Supabase를 쓸지 모르고, prod 웹을 띄우면 웹이 알아서 고른다. 그래서 "앱 환경"은 어느 웹 URL을 띄우는가, 그리고 어떻게 서명·배포하는가로만 갈린다. 웹 dev/prod 매트릭스는 web repo의 책임이다.
+
+- "앱을 테스트한다"는 앱 빌드를 테스트 채널(TestFlight, Play 내부 테스트)로 보내 폰으로 받아 본다는 뜻이다. 어느 빌드든 같은 prod 웹을 가리킨다. 웹의 테스트 버전을 보는 것이 아니다.
+- 별도의 dev 웹 staging은 불필요하다. 브릿지 계약이 additive·gated이므로(`bridge-guide`) 앱 연동 웹 코드를 prod에 올려도 구버전 앱·브라우저에서 안전하다.
+- 링크가 앱 안에 머물지 시스템 브라우저로 나갈지의 경계(`ALLOWED_ORIGINS`)는 `native-app-guide` §링크 경계와 `src/config/env.ts`(SSOT)를 따른다.
+
+## 미리보기·테스트: production 빌드 → 스토어 테스트 채널 (Expo Go 불가, 시뮬레이터 불필요)
+
+이 앱은 네이티브 모듈 때문에 Expo Go로 뜨지 않는다. 비개발자 환경에는 시뮬레이터(Xcode/Android Studio)도 없다고 가정한다. 포장된 길은 production 빌드 하나를 만들어 스토어 테스트 채널로 보내 실폰에서 확인하고, 같은 빌드를 그대로 공개로 승급하는 것이다. 승급 자체는 스토어 콘솔에서 수동으로 한다(아래 §배포·릴리스). 전용 `preview`·ad-hoc 빌드는 만들지 않는다. EAS 빌드 수를 아끼고, 실제 출시 아티팩트를 그대로 검증한다.
+
+```bash
+npx eas-cli build --profile production --platform all --auto-submit
+# iOS → TestFlight, Android → Play 내부 테스트. 폰에서 TestFlight 앱 / 초대 링크로 설치.
+```
+
+- iOS: `eas submit`이 ASC에 업로드하고, 처리(약 10–15분) 후 TestFlight에 올라온다. 내부 테스터(≤100, ASC 팀)는 심사 없이 즉시 설치한다. 공개는 ASC "Submit for Review"로 같은 빌드를 제출한다.
+- Android: AAB가 Play 내부 테스트 트랙에 분 단위로 올라온다(심사 없음). 단 새 개발자 계정은 production 전에 비공개 테스트 12명·14일 연속이 필수다(`store-release-guide`).
+- 빠른 사이드로드(ad-hoc IPA·APK, QR/링크 직접 설치)가 필요하면 `distribution: "internal"` 프로파일을 따로 추가하는 옵션이 있다. 단 iOS는 UDID 등록이 필요하고 그 빌드는 출시로 승급되지 않으므로 기본 경로가 아니다. day-one에는 production 빌드 설치를 단정한다.
+
+## 실기기: prod 웹 https (localhost 함정)
+
+앱은 배포된 prod 웹 https를 로드한다. 실기기는 Owner 컴퓨터의 `localhost`에 도달하지 못하고, http LAN은 secure-context가 아니라서 카메라·마이크·Web Crypto·클립보드·Secure 쿠키가 실기기에서 경고 없이 깨진다(Android cleartext, iOS ATS). 그러니 빌드의 `EXPO_PUBLIC_WEB_URL`은 항상 prod https로 둔다.
+
+`src/config/env.ts` 가드는 protocol/hostname만 본다. https 또는 localhost면 통과한다. 이 가드는 실기기와 시뮬레이터를 구분하지 못한다. localhost URL은 가드를 통과하고도 실기기에서는 깨진다. "실기기 = prod https"는 코드가 강제하는 불변식이 아니라 Owner와 AI가 지키는 규칙이다.
+
+### 고급·선택: 셸을 직접 고칠 때만
+
+네이티브 셸(`Host.tsx` 등)을 빠르게 반복할 때만 `development` 프로파일(dev client)과 `npx expo start`(Metro Fast Refresh)를 쓴다. dev build는 폰이든 시뮬레이터든 어디서나 돈다.
+
+- 시뮬레이터가 있다면(Mac=Xcode/iOS, 전 OS=Android 에뮬) 웹뷰를 `localhost`(iOS 시뮬)·`10.0.2.2`(Android 에뮬)로 가리켜 로컬 웹과 함께 고칠 수 있다. 실기기에서는 금지한다(위 secure-context 함정).
+- `eas.json`의 `development` 프로파일은 기본적으로 https 플레이스홀더에 cleartext/ATS·localhost가 배선되지 않은 상태로 배송된다. 로컬 dev 루프는 AI가 요청 시 세팅하는 레시피다. localhost·`10.0.2.2`와 ATS/cleartext 예외를 `development` 프로파일에만 추가한다(`production`에는 절대 넣지 않는다). 사전 구성된 프로파일이 아니다.
+- 대부분은 여기까지 가지 않는다. 웹 UI는 그냥 브라우저에서 고친다.
+
+## 두 속도 (무엇이 어떻게 반영되나)
+
+| 변경 | 반영 방법 |
+|------|-----------|
+| 네이티브 셸 JS/TSX | Metro Fast Refresh — 즉시 |
+| 웹 변경 | 웹 재배포(or 웹뷰 새로고침) — 앱은 그대로 |
+| 네이티브/config(`app.config.ts`·플러그인·scheme·권한·SDK) | dev build 재빌드 |
+
+`EXPO_PUBLIC_*`는 빌드 시점에 인라인된다. "재빌드 없이 URL 변경"은 약속하지 않는다.
+
+## 배포·릴리스: OTA vs 재빌드
+
+평소 변경(웹)은 웹 배포로 즉시 반영된다. 앱 자체 재출시는 네이티브가 바뀔 때만 한다.
+
+| 변경 | 조치 |
+|------|------|
+| 웹/UI 변경 | 웹 배포 (스토어 액션 0) |
+| RN 셸 순수 JS/TSX/이미지/스타일 | OTA: `npx eas-cli update` |
+| 네이티브 모듈·`app.config.ts`·plugins·scheme·권한·SDK 업·계약 메시지 추가 | 재빌드 + 재제출 |
+
+- `runtimeVersion.policy: "appVersion"`이므로 같은 version 빌드끼리만 OTA가 가능하다.
+- 재제출 시 marketing version(`app.config.ts`의 `version`) 올림이 필수다(ITMS-90186). autoIncrement는 buildNumber/versionCode만 올린다.
+
+## eas build / submit
+
+```bash
+# 스토어 빌드 + 자동 제출 (iOS=TestFlight, Android=내부 트랙까지)
+npx eas-cli build --profile production --platform ios \
+  --auto-submit --non-interactive --no-wait --message "<짧은 설명>"
+```
+
+- 백그라운드 진행은 항상 `--no-wait`로 둔다.
+- `cli.appVersionSource: "remote"`와 `autoIncrement: true`로 buildNumber/versionCode를 EAS가 자동으로 +1 한다.
+- `eas submit`은 공개 심사 제출까지 하지 않는다. iOS는 TestFlight, Android은 internal 트랙까지만 간다. 공개 출시(ASC "Submit for Review", Play production 승급)는 Owner가 수동으로, 명시적 confirm을 받아 한다. Android 첫 AAB는 Play Console에서 수동으로 1회 업로드해야 한다. 첫 자동 제출 실패는 정상이다([Expo: first Android submission](https://github.com/expo/fyi/blob/main/first-android-submission.md)).
+- 자격증명(iOS 인증서·프로비저닝·APNs, Android 키스토어)은 EAS-managed로 자동 생성된다. `eas.json`에는 public 값만 커밋하고, 시크릿은 EAS 서버에 둔다.
+
+## EAS 무료 티어 한도
+
+iOS 15 + Android 15 빌드/월, 동시성 1, 우선순위 Low, 빌드당 45분([Expo 요금](https://expo.dev/pricing)). JS 변경은 빌드 풀을 쓰지 않지만, 초기 네이티브 셋업에는 iOS 빌드를 수 개 소모할 수 있다. "첫 빌드 10–20분 + 큐는 멈춘 게 아님"을 미리 알린다.
+
+## SDK 56 핀 (브레이킹)
+
+- RN 0.85 + React 19.2, Hermes v1 기본.
+- `expo/fetch` 글로벌 기본, `@expo/vector-icons` deprecated → `@react-native-vector-icons/*`.
+- iOS 최소 16.4, Xcode 26.4+.
+- 이벤트 구독 정리는 `subscription.remove()`로 한다(`removeEventListener` 제거).
+
+## 플랫폼 매트릭스
+
+- iOS 시뮬은 Mac/Xcode 전용이다. Windows/Linux는 본인 iPhone과 EAS 클라우드 빌드로 한다(Mac 불필요).
+- Android 에뮬은 전 OS에서 된다(단 Google Play Services 포함 이미지, AOSP 아님).
+- 실기기 검증 항목: 로그인은 웹뷰 안의 웹 로그인 UI가 뜬다(셸 기능이 아님). 푸시는 v1에는 없다. 푸시를 추가했을 때만 원격 푸시를 실기기에서 검증한다(시뮬 푸시는 sandbox라 prod 검증이 아니다). 네이티브 소셜은 비활성 "coming soon" 스텁이라 v1에는 검증 대상이 없다(추가 시 Apple `getCredentialStateAsync`는 시뮬에서 항상 에러).
+
+## 필수 안전장치
+
+- `src/config/env.ts`는 `EXPO_PUBLIC_WEB_URL`을 시작 시점에 명시적 throw로 가드한다(미설정·빈 값·URL 파싱 실패·non-https-non-localhost). protocol/hostname만 검사하므로 실기기와 시뮬을 구분하지 못한다(위 참조).
+- `.env`는 커밋하지 않는다(`.gitignore`가 `.env`/`.env.*`를 제외하고 `.env.example`만 유지). 커밋되는 `.env.example`에는 플레이스홀더(`https://your-app.vercel.app`)만 들어간다. 인라인 소스는 클라우드 빌드는 `eas.json`의 `build.<profile>.env`, 로컬 `expo start`는 Owner가 만든 `.env`다.
+- 테스트와 출시 모두 production(store) 프로파일 하나를 쓴다. TestFlight(iOS), Play 내부 테스트(Android). ad-hoc 사이드로드가 필요할 때만 `distribution: internal` 프로파일을 따로 추가한다(UDID 한정, 출시로 승급되지 않음).
+
+## 빌드 모니터링
+
+Expo 대시보드 빌드 페이지에서 진행을 확인한다. 첫 빌드는 큐 포함 10–20분이 걸린다(멈춘 게 아님). 백그라운드는 항상 `--no-wait`로 둔다.