create-saas-starter-workspace 0.1.0

package/templates/workspace/scripts/doctor.mjs

@@ -0,0 +1,291 @@
+// doctor — 워크스페이스 생성 이후의 환경·로그인 상태를 결정적으로 점검한다.
+//
+// 실행: 워크스페이스 루트에서 `pnpm doctor` (또는 `node scripts/doctor.mjs`).
+// 의존성 0 — node 내장 모듈만 쓴다. 루트에는 node_modules가 없어도 돈다.
+//
+// 원칙:
+//   - 절대 중간에 죽지 않는다. 모든 검사를 감싸고, 실패해도 끝까지 점검해 전체 그림을 보여준다.
+//   - 각 ✗에는 "정확히 무엇을 하면 되는지"를 함께 출력한다. 셀프 페이스 강의에서 이 안내가 조교다.
+//   - 진단·안내까지만 한다. 자동 수리는 하지 않는다(수리는 안내문 또는 코딩 에이전트에 위임).
+//   - [앱] 섹션은 "앱으로 확장" 챕터 전까지 ✗여도 정상이며, 웹 준비 판정에 포함하지 않는다.
+//
+// 부트스트랩 단계의 점검(Node가 깔렸나 등)은 부트스트랩 자신의 책임이다. 이 파일의 책임은 생성 이후다.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const WIN = process.platform === "win32";
+
+// ---------- 출력 ----------
+
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (code, s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+const green = (s) => c("32", s);
+const red = (s) => c("31", s);
+const yellow = (s) => c("33", s);
+const dim = (s) => c("2", s);
+const bold = (s) => c("1", s);
+
+const MARK = { ok: green("✓"), fail: red("✗"), warn: yellow("⚠") };
+
+// ---------- 명령 실행 (절대 throw하지 않는다) ----------
+
+function run(cmd, { cwd = ROOT, timeout = 15000 } = {}) {
+  try {
+    // shell: true — PATH의 셸 셔임(.cmd 등)까지 OS 방식대로 해석하게 한다. cmd는 전부
+    // 이 파일이 소유한 고정 문자열이라 인젝션 표면이 없다.
+    const r = spawnSync(cmd, { shell: true, cwd, timeout, encoding: "utf8" });
+    const stdout = (r.stdout ?? "").trim();
+    const stderr = (r.stderr ?? "").trim();
+    return {
+      ok: r.status === 0,
+      timedOut: r.error?.code === "ETIMEDOUT",
+      // 오프라인·DNS 실패를 "로그인 안 됨"으로 오진하지 않기 위한 신호.
+      networkIssue: /ENOTFOUND|ECONNREFUSED|ECONNRESET|EAI_AGAIN|fetch failed|getaddrinfo|network/i.test(stdout + stderr),
+      stdout,
+      stderr,
+    };
+  } catch {
+    return { ok: false, timedOut: false, networkIssue: false, stdout: "", stderr: "" };
+  }
+}
+
+const installed = (bin) => run(WIN ? `where ${bin}` : `command -v ${bin}`, { timeout: 8000 }).ok;
+
+// ---------- 워크스페이스 메타 ----------
+
+function readWorkspaceMeta() {
+  try {
+    return JSON.parse(readFileSync(path.join(ROOT, "workspace.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+// ---------- 개별 검사 ----------
+// 각 검사는 { status: "ok"|"fail"|"warn", label, detail?, fix? }를 반환한다.
+
+function checkNode() {
+  const major = Number(process.version.slice(1).split(".")[0]);
+  if (major >= 22) return { status: "ok", label: `Node.js ${process.version}` };
+  if (major >= 20)
+    return {
+      status: "warn",
+      label: `Node.js ${process.version}`,
+      detail: "동작은 하지만 22 이상을 권장합니다.",
+      fix: "강의의 설치 명령(setup)을 다시 실행하면 LTS로 올려 줍니다.",
+    };
+  return {
+    status: "fail",
+    label: `Node.js ${process.version}`,
+    detail: "버전이 너무 낮습니다 (22 이상 필요).",
+    fix: "강의의 설치 명령(setup)을 다시 실행하세요.",
+  };
+}
+
+function checkPnpm() {
+  const r = run("pnpm --version", { timeout: 10000 });
+  if (!r.ok)
+    return { status: "fail", label: "pnpm", detail: "설치되어 있지 않습니다.", fix: "npm install -g pnpm@10" };
+  const major = Number(r.stdout.split(".")[0]);
+  if (major >= 10) return { status: "ok", label: `pnpm ${r.stdout}` };
+  return { status: "warn", label: `pnpm ${r.stdout}`, detail: "10 이상을 권장합니다.", fix: "npm install -g pnpm@10" };
+}
+
+function checkGit() {
+  const r = run("git --version", { timeout: 10000 });
+  return r.ok
+    ? { status: "ok", label: r.stdout.replace("git version ", "git ") }
+    : { status: "fail", label: "git", detail: "설치되어 있지 않습니다.", fix: "강의의 설치 명령(setup)을 다시 실행하세요." };
+}
+
+// 코딩 에이전트 — workspace.json의 선택값을 우선 점검하고, 없으면 발견되는 것을 쓴다.
+const AGENTS = {
+  claude: { bin: "claude", name: "Claude Code", install: "https://claude.com/claude-code 의 설치 안내", login: "터미널에 claude 를 입력하고 안내에 따라 로그인" },
+  codex: { bin: "codex", name: "Codex", install: "npm install -g @openai/codex", login: "codex login" },
+  opencode: { bin: "opencode", name: "OpenCode", install: "npm install -g opencode-ai", login: "opencode auth login" },
+};
+
+function agentLoggedIn(key) {
+  // 로그인 상태는 에이전트마다 확인 수단이 달라 best-effort다. 판별 불가면 null을 돌려주고
+  // 호출자가 ⚠(직접 확인 안내)로 처리한다.
+  if (key === "codex") {
+    const r = run("codex login status", { timeout: 10000 });
+    return r.ok ? true : /not logged|로그인/i.test(r.stdout + r.stderr) ? false : null;
+  }
+  if (key === "opencode") {
+    // `opencode auth list`는 자격증명이 없어도 장식 출력(헤더 등)을 내므로,
+    // "출력이 있다 = 로그인됨"으로 단정하면 오탐이 난다. 명확할 때만 판정하고 아니면 null(⚠).
+    const r = run("opencode auth list", { timeout: 10000 });
+    if (!r.ok) return null;
+    if (/no credentials|not logged/i.test(r.stdout + r.stderr)) return false;
+    return null;
+  }
+  if (key === "claude") {
+    // Claude Code는 자격증명을 macOS 키체인 또는 ~/.claude/.credentials.json에 둔다.
+    if (process.platform === "darwin") {
+      const r = run(`security find-generic-password -s "Claude Code-credentials"`, { timeout: 8000 });
+      if (r.ok) return true;
+    }
+    if (existsSync(path.join(os.homedir(), ".claude", ".credentials.json"))) return true;
+    return null;
+  }
+  return null;
+}
+
+function checkAgent(meta) {
+  const selected = AGENTS[meta.agent] ? meta.agent : null;
+  const found = Object.keys(AGENTS).filter((k) => installed(AGENTS[k].bin));
+
+  const key = selected && found.includes(selected) ? selected : selected ? null : found[0] ?? null;
+
+  if (selected && key === null) {
+    const others = found.map((k) => AGENTS[k].name).join(", ");
+    return {
+      status: "fail",
+      label: `코딩 에이전트 (${AGENTS[selected].name})`,
+      detail: `선택한 ${AGENTS[selected].name}가 설치되어 있지 않습니다.` + (others ? ` (발견됨: ${others})` : ""),
+      fix: `설치: ${AGENTS[selected].install}`,
+    };
+  }
+  if (!key) {
+    return {
+      status: "fail",
+      label: "코딩 에이전트",
+      detail: "Claude Code / Codex / OpenCode 중 어느 것도 찾지 못했습니다.",
+      fix: `Claude Code 설치: ${AGENTS.claude.install}`,
+    };
+  }
+  const auth = agentLoggedIn(key);
+  if (auth === true) return { status: "ok", label: `코딩 에이전트 (${AGENTS[key].name}) — 설치·로그인` };
+  if (auth === false)
+    return {
+      status: "fail",
+      label: `코딩 에이전트 (${AGENTS[key].name})`,
+      detail: "설치는 되어 있지만 로그인이 안 되어 있습니다.",
+      fix: AGENTS[key].login,
+    };
+  return {
+    status: "warn",
+    label: `코딩 에이전트 (${AGENTS[key].name}) — 설치됨`,
+    detail: "로그인 상태는 여기서 판별할 수 없습니다.",
+    fix: `확인: ${AGENTS[key].login} (이미 로그인했다면 그대로 두면 됩니다)`,
+  };
+}
+
+function checkGh() {
+  if (!installed("gh"))
+    return { status: "fail", label: "GitHub CLI (gh)", detail: "설치되어 있지 않습니다.", fix: "강의의 설치 명령(setup)을 다시 실행하세요." };
+  const r = run("gh auth status", { timeout: 15000 });
+  return r.ok
+    ? { status: "ok", label: "GitHub CLI (gh) — 로그인됨" }
+    : { status: "fail", label: "GitHub CLI (gh)", detail: "로그인이 안 되어 있습니다.", fix: "gh auth login --web --git-protocol https" };
+}
+
+function checkVercel() {
+  if (!installed("vercel"))
+    return { status: "fail", label: "Vercel CLI", detail: "설치되어 있지 않습니다.", fix: "npm install -g vercel" };
+  const r = run("vercel whoami", { timeout: 20000 });
+  if (r.ok) return { status: "ok", label: `Vercel CLI — 로그인됨 (${r.stdout.split("\n").pop()})` };
+  if (r.timedOut || r.networkIssue)
+    return { status: "warn", label: "Vercel CLI", detail: "네트워크 문제로 확인하지 못했습니다.", fix: "인터넷 연결 후 pnpm doctor 재실행" };
+  return { status: "fail", label: "Vercel CLI", detail: "로그인이 안 되어 있습니다.", fix: "vercel login" };
+}
+
+function checkSupabase() {
+  const bin = path.join(ROOT, "web", "node_modules", ".bin", WIN ? "supabase.CMD" : "supabase");
+  if (!existsSync(bin))
+    return {
+      status: "fail",
+      label: "Supabase CLI",
+      detail: "web/ 의존성에 포함된 CLI를 찾지 못했습니다 (설치 전?).",
+      fix: "cd web && pnpm install --frozen-lockfile",
+    };
+  const r = run(`"${bin}" projects list`, { cwd: path.join(ROOT, "web"), timeout: 25000 });
+  if (r.ok) return { status: "ok", label: "Supabase CLI — 로그인됨" };
+  if (r.timedOut || r.networkIssue)
+    return { status: "warn", label: "Supabase CLI", detail: "네트워크 문제로 확인하지 못했습니다.", fix: "인터넷 연결 후 pnpm doctor 재실행" };
+  return {
+    status: "fail",
+    label: "Supabase CLI",
+    detail: "로그인이 안 되어 있습니다.",
+    fix: "cd web && pnpm exec supabase login",
+  };
+}
+
+const checkDeps = (sub) =>
+  existsSync(path.join(ROOT, sub, "node_modules"))
+    ? { status: "ok", label: `${sub}/ 의존성 설치됨` }
+    : { status: "fail", label: `${sub}/ 의존성`, detail: "node_modules가 없습니다.", fix: `cd ${sub} && pnpm install --frozen-lockfile` };
+
+function checkEas() {
+  if (!installed("eas"))
+    return { status: "fail", label: "EAS CLI", detail: "설치되어 있지 않습니다.", fix: "npm install -g eas-cli" };
+  const r = run("eas whoami", { timeout: 20000 });
+  if (r.ok) return { status: "ok", label: `EAS CLI — 로그인됨 (${r.stdout.split("\n").pop()})` };
+  if (r.timedOut || r.networkIssue)
+    return { status: "warn", label: "EAS CLI", detail: "네트워크 문제로 확인하지 못했습니다.", fix: "인터넷 연결 후 pnpm doctor 재실행" };
+  return {
+    status: "fail",
+    label: "EAS CLI",
+    detail: "로그인이 안 되어 있습니다.",
+    fix: "eas login (Expo 계정이 없다면 expo.dev에서 가입 — '앱으로 확장' 챕터에서 안내)",
+  };
+}
+
+// ---------- 실행 ----------
+
+const meta = readWorkspaceMeta();
+
+console.log("");
+console.log(bold(`🩺 doctor — ${meta.name ?? path.basename(ROOT)} 환경 점검`));
+console.log(dim("   각 항목을 점검합니다. 네트워크 확인이 포함되어 몇십 초 걸릴 수 있습니다."));
+
+const sections = [
+  { title: "공통", blocking: true, checks: [checkNode, checkPnpm, checkGit, () => checkAgent(meta), checkGh, checkVercel] },
+  { title: "웹", blocking: true, checks: [() => checkDeps("web"), checkSupabase] },
+  { title: "앱", blocking: false, note: "'앱으로 확장' 챕터 전까지는 ✗여도 정상입니다.", checks: [() => checkDeps("mobile"), checkEas] },
+];
+
+let blockingFails = 0;
+let appFails = 0;
+let warns = 0;
+
+for (const section of sections) {
+  console.log("");
+  console.log(bold(`[${section.title}]`) + (section.note ? dim(`  ${section.note}`) : ""));
+  for (const check of section.checks) {
+    let result;
+    try {
+      result = check();
+    } catch (e) {
+      // 어떤 검사도 doctor 전체를 멈추지 못한다.
+      result = { status: "warn", label: "내부 오류", detail: String(e?.message ?? e) };
+    }
+    console.log(`  ${MARK[result.status]} ${result.label}`);
+    if (result.detail) console.log(`     ${dim(result.detail)}`);
+    if (result.fix && result.status !== "ok") console.log(`     ${yellow("→ " + result.fix)}`);
+    if (result.status === "fail") section.blocking ? blockingFails++ : appFails++;
+    if (result.status === "warn") warns++;
+  }
+}
+
+console.log("");
+if (blockingFails === 0) {
+  console.log(green(bold("✅ 웹 개발 준비 완료")) + (warns ? dim(`  (⚠ ${warns}개는 안내를 참고해 직접 확인하세요)`) : ""));
+} else {
+  console.log(red(bold(`✗ ${blockingFails}개 항목이 남았습니다.`)) + " 위의 → 안내를 따라 해결한 뒤 다시 실행하세요: " + bold("pnpm doctor"));
+  console.log("");
+  console.log("📋 직접 하기 어렵다면, 코딩 에이전트에 아래 문장을 그대로 붙여넣으세요:");
+  console.log(bold('   "pnpm doctor를 실행해서 ✗ 항목을 확인하고, 각 항목의 → 안내를 따라 해결해줘.'));
+  console.log(bold('    브라우저 로그인이 필요한 단계는 멈추고 나에게 알려줘. 끝나면 pnpm doctor로 다시 검증해줘."'));
+}
+if (appFails > 0 && blockingFails === 0) {
+  console.log(dim(`📦 [앱] ✗ ${appFails}개는 '앱으로 확장' 챕터에서 해결합니다. 지금은 무시해도 됩니다.`));
+}
+console.log("");
+
+process.exit(blockingFails === 0 ? 0 : 1);

package/templates/workspace/ssb/README.md

@@ -0,0 +1,10 @@
+# ssb — 앱↔웹 브릿지 계약 (SSOT)
+
+이 폴더가 앱↔웹 통신 계약의 원본이다. 메시지는 `ns: "ssb"` 네임스페이스를 달아 페이지의 다른 postMessage 트래픽과 섞이지 않는다. `/kickoff`이 여기서 app(`src/bridge/`)과 web(`lib/bridge/`)으로 바이트 단위로 동일하게 복사하고, CI checksum이 드리프트를 막는다.
+
+불변식 (상세는 `contract.ts` 헤더):
+
+- 추가만 허용한다(append-only): 타입·옵셔널 필드만 추가하고, 제거·이름변경·필수화는 하지 않는다. 구버전 앱과 최신 웹이 서로 호환된다.
+- reader는 tolerant하다: 모르는·깨진 메시지는 `UNKNOWN`이 되고 예외를 던지지 않는다.
+- 토큰은 브릿지로 보내지 않는다. 세션 핸드오프는 1회용 nonce로 server가 Set-Cookie한다.
+- 기능 분기는 HELLO의 `capabilities`(문자열 배열)로 하고, 버전 번호로 하지 않는다.

package/templates/workspace/ssb/contract.ts

@@ -0,0 +1,146 @@
+import { z } from "zod";
+
+/**
+ * App ↔ Web bridge contract — SINGLE SOURCE OF TRUTH.
+ *
+ * This file is copied byte-for-byte into the web project (docs/web-adapter/contract.ts).
+ * The two MUST stay identical; the web adapter ships a checksum check to enforce it.
+ *
+ * Invariants (never break these):
+ *  1. Every message is namespaced (`ns: "ssb"`) so unrelated postMessage traffic on
+ *     the page is ignored.
+ *  2. The contract is ADDITIVE-ONLY. Add new message `type`s or new OPTIONAL payload
+ *     fields; never remove a type, rename one, or make an existing field required.
+ *     Old apps must keep working against new webs and vice-versa.
+ *  3. Features are gated by HELLO `capabilities` (a string array), NOT by version
+ *     number. The app advertises what it can do; the web feature-detects.
+ *  4. The reader (reader.ts) is tolerant: anything unrecognized becomes UNKNOWN and
+ *     never throws.
+ *  5. Auth tokens NEVER travel over this channel. Session handoff is a server
+ *     Set-Cookie via a one-time nonce (see src/session + docs/web-adapter).
+ */
+
+export const SSB_NS = "ssb" as const;
+export const SSB_PROTOCOL_VERSION = 1 as const;
+
+/** All message type names. Add here (append-only) when extending the contract. */
+export const MSG = {
+  // ── app → web ──
+  /** App announces itself + capabilities as soon as the page is reachable. */
+  HELLO: "HELLO",
+  /** App confirms a web session cookie was installed (after native login handoff). */
+  SESSION_INSTALLED: "SESSION_INSTALLED",
+  /** App confirms it cleared its local session copy after a logout. */
+  LOGOUT_DONE: "LOGOUT_DONE",
+  /** Forward-compat only — push is a fast-follow; defined so the web can feature-detect later. */
+  PUSH_TOKEN_UPDATED: "PUSH_TOKEN_UPDATED",
+
+  // ── web → app ──
+  /** Web acknowledges the bridge is live (handshake completes). */
+  READY: "READY",
+  /** Web has no session and asks the app to run native login + install a session. */
+  REQUEST_SESSION_INSTALL: "REQUEST_SESSION_INSTALL",
+  /** Web tells the app its auth state changed (e.g. user logged in/out inside the webview). */
+  AUTH_STATE_CHANGED: "AUTH_STATE_CHANGED",
+  /** Web asks the app to forget the session (user logged out). */
+  LOGOUT: "LOGOUT",
+  /** Web asks the app to open a URL in the system browser instead of the webview. */
+  OPEN_EXTERNAL: "OPEN_EXTERNAL",
+
+  // ── reader fallback (not a wire message) ──
+  UNKNOWN: "UNKNOWN",
+} as const;
+
+export type MessageType = (typeof MSG)[keyof typeof MSG];
+
+/** Fields shared by every envelope. */
+const envelopeBase = {
+  ns: z.literal(SSB_NS),
+  v: z.number().int(),
+  /** Correlation id, present on request/response pairs. */
+  id: z.string().optional(),
+};
+
+// ───────────────────────── web → app (inbound) ─────────────────────────
+const ReadyMessage = z.object({
+  ...envelopeBase,
+  type: z.literal(MSG.READY),
+  payload: z.object({}).optional(),
+});
+
+const RequestSessionInstallMessage = z.object({
+  ...envelopeBase,
+  type: z.literal(MSG.REQUEST_SESSION_INSTALL),
+  payload: z.object({ redirectPath: z.string().optional() }).optional(),
+});
+
+const AuthStateChangedMessage = z.object({
+  ...envelopeBase,
+  type: z.literal(MSG.AUTH_STATE_CHANGED),
+  payload: z.object({ authenticated: z.boolean() }),
+});
+
+const LogoutMessage = z.object({
+  ...envelopeBase,
+  type: z.literal(MSG.LOGOUT),
+  payload: z.object({}).optional(),
+});
+
+const OpenExternalMessage = z.object({
+  ...envelopeBase,
+  type: z.literal(MSG.OPEN_EXTERNAL),
+  payload: z.object({ url: z.string() }),
+});
+
+export const InboundSchema = z.discriminatedUnion("type", [
+  ReadyMessage,
+  RequestSessionInstallMessage,
+  AuthStateChangedMessage,
+  LogoutMessage,
+  OpenExternalMessage,
+]);
+export type InboundMessage = z.infer<typeof InboundSchema>;
+
+// ───────────────────────── app → web (outbound) ─────────────────────────
+const HelloMessage = z.object({
+  ...envelopeBase,
+  type: z.literal(MSG.HELLO),
+  payload: z.object({
+    protocolVersion: z.number().int(),
+    capabilities: z.array(z.string()),
+    appVersion: z.string(),
+    platform: z.enum(["ios", "android"]),
+  }),
+});
+
+const SessionInstalledMessage = z.object({
+  ...envelopeBase,
+  type: z.literal(MSG.SESSION_INSTALLED),
+  payload: z.object({ ok: z.boolean() }),
+});
+
+const LogoutDoneMessage = z.object({
+  ...envelopeBase,
+  type: z.literal(MSG.LOGOUT_DONE),
+  payload: z.object({}).optional(),
+});
+
+const PushTokenUpdatedMessage = z.object({
+  ...envelopeBase,
+  type: z.literal(MSG.PUSH_TOKEN_UPDATED),
+  payload: z.object({ token: z.string() }),
+});
+
+export const OutboundSchema = z.discriminatedUnion("type", [
+  HelloMessage,
+  SessionInstalledMessage,
+  LogoutDoneMessage,
+  PushTokenUpdatedMessage,
+]);
+export type OutboundMessage = z.infer<typeof OutboundSchema>;
+
+/**
+ * The tolerant reader's fallback shape. Not a valid wire message — produced only
+ * when an inbound payload cannot be understood. See reader.ts.
+ */
+export type UnknownMessage = { type: typeof MSG.UNKNOWN; raw: unknown };

package/templates/workspace/ssb/reader.ts

@@ -0,0 +1,31 @@
+import { InboundSchema, MSG, type InboundMessage, type UnknownMessage } from "./contract";
+
+export type ReadResult = InboundMessage | UnknownMessage;
+
+/**
+ * Tolerant reader for messages arriving FROM the web (WebView `onMessage`).
+ *
+ * Hard contract: this function NEVER throws. Anything it cannot confidently
+ * understand — wrong namespace, non-JSON string, unknown `type`, missing/invalid
+ * fields, a number, null — collapses to `{ type: "UNKNOWN", raw }`. The native
+ * shell must survive hostile, outdated, or unrelated postMessage traffic.
+ *
+ * `raw` is whatever `event.nativeEvent.data` gave us (usually a JSON string, but
+ * a parsed object is accepted too).
+ */
+export function readInbound(raw: unknown): ReadResult {
+  let candidate: unknown = raw;
+
+  if (typeof raw === "string") {
+    try {
+      candidate = JSON.parse(raw);
+    } catch {
+      return { type: MSG.UNKNOWN, raw };
+    }
+  }
+
+  const parsed = InboundSchema.safeParse(candidate);
+  if (parsed.success) return parsed.data;
+
+  return { type: MSG.UNKNOWN, raw };
+}

package/templates/workspace/web/.env.example

@@ -0,0 +1,39 @@
+# ─────────────────────────────────────────────────────────────
+# my-space — 환경변수 명세
+#
+# 이 파일엔 *키 이름과 어느 환경에 들어가는지*만 있다.
+# 실제 값은 /go-live가 Vercel에 박은 뒤 `vercel env pull` 로 동기화.
+# ─────────────────────────────────────────────────────────────
+
+# ─── Supabase (dev/prod 별개 프로젝트) ──────────────────────────
+# Vercel "Development" + "Preview" → dev 프로젝트 값
+# Vercel "Production"               → prod 프로젝트 값
+NEXT_PUBLIC_SUPABASE_URL=
+# 새 키 시스템 (2026): sb_publishable_xxx 형식. 레거시 anon JWT도 호환되나 신규 권장.
+NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
+
+# 서버 전용. NEXT_PUBLIC_ 절대 금지. sb_secret_xxx 형식 (구 service_role 대체).
+SUPABASE_SECRET_KEY=
+
+# Supabase 프로젝트 ref (마이그레이션 CLI 인자)
+SUPABASE_DEV_REF=
+SUPABASE_PROD_REF=
+
+# Supabase Management API Personal Access Token
+# (Auth redirect URL 등 CLI 미커버 항목 자동화용)
+# → 셸 rc에 export 권장. 이 파일에는 두지 말 것.
+# SUPABASE_ACCESS_TOKEN=
+
+# ─── Sentry ──────────────────────────────────────────────────
+NEXT_PUBLIC_SENTRY_DSN=
+SENTRY_AUTH_TOKEN=
+SENTRY_ORG=
+SENTRY_PROJECT=
+
+# ─── 배포 환경 ─────────────────────────────────────────────────
+# 코드 분기는 벤더 중립 APP_ENV로 한다(lib/app-env.ts).
+# Vercel은 아래를 자동 주입하므로 설정 불필요(VERCEL_ENV가 APP_ENV로 매핑됨).
+# VERCEL_ENV=production | preview | development
+# VERCEL_URL=<deployment-url>
+# 그 외 호스트에 배포할 때만 직접 설정:
+# APP_ENV=production | preview | development

package/templates/workspace/web/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

package/templates/workspace/web/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    name: typecheck · lint · test · build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      # pnpm 버전은 package.json의 packageManager 필드에서 읽는다.
+      # (version 입력을 함께 주면 두 값이 충돌해 action이 실패한다.)
+      - uses: pnpm/action-setup@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: lts/*   # 현재 LTS 자동 해석. 수동 갱신 불요.
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Audit (high/critical only)
+        # 알려진 CVE·악성 advisory 발견 시 빌드 실패.
+        # cooldown(.npmrc minimum-release-age)은 미공개·신선한 위험을 막고,
+        # audit은 공개된 known vulnerability를 막는다.
+        run: pnpm audit --prod --audit-level=high
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Lint
+        # lint:ci = eslint --max-warnings 0
+        # `@typescript-eslint/no-deprecated`가 warn level로 들어오므로 여기서 차단.
+        run: pnpm lint:ci
+
+      - name: Test
+        run: pnpm test
+        env:
+          # env.ts가 모듈 로드 시 zod 파싱하므로 테스트 임포트만으로도 필요.
+          # 단위 테스트는 외부 호출 X (mock 사용) — 더미 또는 GH Secrets 둘 다 OK.
+          NEXT_PUBLIC_SUPABASE_URL: ${{ secrets.NEXT_PUBLIC_SUPABASE_URL }}
+          NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY: ${{ secrets.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY }}
+
+      - name: Build
+        run: pnpm build
+        env:
+          NEXT_PUBLIC_SUPABASE_URL: ${{ secrets.NEXT_PUBLIC_SUPABASE_URL }}
+          NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY: ${{ secrets.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY }}
+          NEXT_PUBLIC_SENTRY_DSN: ${{ secrets.NEXT_PUBLIC_SENTRY_DSN }}
+          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
+          SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
+          SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }}

package/templates/workspace/web/.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+  "files.associations": {
+    "*.css": "tailwindcss"
+  },
+  "editor.quickSuggestions": {
+    "strings": "on"
+  }
+}