sh-ui-cli 0.31.1 → 0.32.0

package/data/changelog/versions.json

@@ -2,6 +2,19 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.32.0",
+      "date": "2026-04-29",
+      "title": "auth-jwt 플러그인 신설 + isomorphic HTTP transport 재설계",
+      "type": "minor",
+      "highlights": [
+        "신규 --plugins auth-jwt — Next 16 proxy.ts 미들웨어, refresh placeholder, withAuthRetry 헬퍼, refresh-aware BFF 를 한 번에 추가. 백엔드 refresh API 명세 확정 후 refreshSession.ts 본문만 채우면 자동 활성화",
+        "베이스 HTTP 레이어 재설계 — axios 단일 인스턴스를 isomorphic http() + serverFetch / clientFetch 두 갈래 transport 로 교체. RSC 는 백엔드 직통, 브라우저는 /api/proxy 경유 → API 함수는 한 번만 작성하고 RSC prefetch + hydration 패턴과 자연스럽게 어울림",
+        "Sentry 플러그인 슬림화 — HTTP/proxy 인프라 파일을 베이스로 이관하고, Sentry 는 observability.ts 를 Sentry-aware 버전으로 덮어써 5xx 캡처/로깅을 활성화. 두 플러그인이 독립적으로 조합됨",
+        "queryClient.ts 추가 — React cache() 기반 RSC 스코프 + 브라우저 싱글톤. 요청 간 캐시 누수 방지. apps/docs 의 auth / api-layer / testing 레시피도 새 설계에 맞춰 갱신"
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.32.0"
+    },
     {
       "version": "0.31.1",
       "date": "2026-04-28",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh-ui-cli",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "description": "sh-ui CLI — 프로젝트 스캐폴드(create) + 컴포넌트 추가(add/list/remove) + IDE-내 AI용 MCP 서버",
   "license": "MIT",
   "repository": {

package/src/create/cli-args.js

@@ -1,6 +1,6 @@
 const VALID_PLATFORMS = ['next', 'flutter'];
 const VALID_STRUCTURES = ['standalone', 'monorepo'];
-const VALID_PLUGINS = ['sentry', 'next-intl'];
+const VALID_PLUGINS = ['sentry', 'next-intl', 'auth-jwt'];
 
 const VALUE_FLAGS = ['platform', 'structure', 'plugins', 'theme', 'app'];
 const BOOL_FLAGS = ['yes', 'help'];

package/src/create/index.mjs

@@ -13,7 +13,7 @@ export const HELP_TEXT = `sh-ui create — sh-ui 프로젝트 스캐폴드 (Next
 옵션:
   --platform <next|flutter>          타겟 플랫폼
   --structure <standalone|monorepo>  Next.js 프로젝트 구조 (next 일 때)
-  --plugins <a,b>                    플러그인 (sentry, next-intl). 미지정/"" → 없음
+  --plugins <a,b>                    플러그인 (sentry, next-intl, auth-jwt). 미지정/"" → 없음
   --theme <base64>                   테마 JSON (base64). 선택
   --yes                              디렉토리 덮어쓰기 + 모노레포 기본값 자동 채택
   -h, --help                         이 도움말

package/src/create/plugins/authJwt.js

@@ -0,0 +1,340 @@
+export const authJwtPlugin = {
+  name: 'auth-jwt',
+  label: '쿠키 기반 JWT 인증 (refresh 자리표시자 포함)',
+  priority: 2,
+
+  // 의존성 추가 없음 — 베이스의 fetch + cookies + react-query 만 사용
+
+  envVars: [
+    '# Auth (auth-jwt)',
+    'COOKIE_SECURE=false',
+  ],
+
+  turboEnvVars: [
+    'COOKIE_SECURE',
+  ],
+
+  providerImports: [],
+  providerWrappers: [],
+
+  // ─── 독립 파일 ───
+  //
+  // 베이스의 BFF (app/api/proxy/[...path]/route.ts) 를 refresh-aware 버전으로
+  // 덮어쓰고, 미들웨어와 인증 헬퍼를 추가한다.
+  // refreshSession.ts 는 v1 placeholder — 백엔드 명세 확정 후 본문만 채우면
+  // BFF 와 withAuthRetry 가 자동 활용한다.
+
+  files: {
+    'src/proxy.ts': `import { NextRequest, NextResponse } from 'next/server';
+
+const AUTH_ROUTES = ['/sign-in', '/sign-up'];
+
+/**
+ * Next 16+ 의 proxy.ts (구 middleware.ts).
+ * 토큰 존재 여부만 검사한다 — 만료 검사나 refresh 는 하지 않는다.
+ *
+ * - AT 쿠키 없음 + 인증 라우트 아님 → /sign-in 으로 리다이렉트
+ * - AT 쿠키 있음 또는 인증 라우트 → 통과
+ *
+ * AT 가 만료된 채 통과한 요청은 BFF (/api/proxy) 가 401 을 받아
+ * refreshSession 으로 갱신을 시도한다.
+ */
+export default function proxy(req: NextRequest) {
+  const { pathname } = req.nextUrl;
+  const hasToken = !!req.cookies.get('accessToken')?.value;
+  const isAuthRoute = AUTH_ROUTES.some((r) => pathname.startsWith(r));
+
+  if (isAuthRoute) return NextResponse.next();
+  if (!hasToken) return NextResponse.redirect(new URL('/sign-in', req.url));
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: '/((?!api|_next|.*\\\\..*).*)',
+};
+`,
+
+    'src/shared/api/refreshSession.ts': `type RefreshResult =
+  | { ok: true; accessToken: string; refreshToken: string }
+  | { ok: false };
+
+let inflight: Promise<RefreshResult> | null = null;
+
+/**
+ * refreshToken 으로 새 accessToken / refreshToken 을 발급받는다.
+ *
+ * v1 placeholder — 백엔드 refresh API 명세가 확정되면 아래 TODO 부분을 채운다.
+ * 본문이 채워지면 BFF (/api/proxy) 와 withAuthRetry 가 자동으로 활용한다.
+ *
+ * 동시에 여러 요청이 401 을 만나도 inflight 모듈 변수로 코얼레싱돼서
+ * refresh 는 한 번만 발사된다.
+ *
+ * 참고 구현 예시:
+ *
+ *   const res = await fetch(\`\${process.env.API_URL}/v1/auth/token/refresh\`, {
+ *     method: 'POST',
+ *     headers: { 'Content-Type': 'application/json' },
+ *     body: JSON.stringify({ refreshToken }),
+ *   });
+ *   const body = await res.json();
+ *   if (body.result === 'SUCCESS') {
+ *     return {
+ *       ok: true,
+ *       accessToken: body.data.accessToken,
+ *       refreshToken: body.data.refreshToken,
+ *     };
+ *   }
+ *   return { ok: false };
+ */
+export async function refreshSession(
+  refreshToken: string,
+): Promise<RefreshResult> {
+  if (inflight) return inflight;
+
+  inflight = (async (): Promise<RefreshResult> => {
+    try {
+      // TODO: 백엔드 refresh API 명세 확정 후 여기에 fetch 호출을 작성.
+      // 지금은 placeholder 라 항상 실패 → BFF 가 쿠키 삭제 + 401 응답.
+      void refreshToken;
+      return { ok: false };
+    } finally {
+      inflight = null;
+    }
+  })();
+
+  return inflight;
+}
+`,
+
+    'src/shared/api/withAuthRetry.ts': `import { cookies } from 'next/headers';
+
+import { ApiError } from './error';
+import { refreshSession } from './refreshSession';
+
+const ACCESS_TOKEN_COOKIE = 'accessToken';
+const REFRESH_TOKEN_COOKIE = 'refreshToken';
+
+const COOKIE = {
+  httpOnly: true,
+  secure: process.env.COOKIE_SECURE === 'true',
+  sameSite: 'lax' as const,
+  path: '/',
+};
+
+/**
+ * Route Handler 또는 Server Action 안에서 인증된 요청을 보낼 때 사용한다.
+ * 401 을 만나면 refreshSession 으로 토큰을 갱신하고 fn 을 한 번 더 실행한다.
+ *
+ * RSC (Server Component) 에서는 cookies().set() 이 막혀 있으므로 여기서 호출하면 안 된다.
+ * RSC 는 serverFetch 를 직접 호출하고, 401 은 prefetchQuery 가 swallow 한 뒤
+ * 클라이언트 refetch 가 BFF 경유로 자동 복구한다.
+ *
+ * 사용 예 (Server Action):
+ *
+ *   'use server';
+ *   import { serverFetch } from '@/src/shared/api/serverFetch';
+ *   import { withAuthRetry } from '@/src/shared/api/withAuthRetry';
+ *
+ *   export async function toggleFavoriteAction(id: number) {
+ *     return withAuthRetry(() =>
+ *       serverFetch(\`/v1/products/\${id}/favorite\`, { method: 'POST' }),
+ *     );
+ *   }
+ */
+export async function withAuthRetry<T>(fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (e) {
+    if (!(e instanceof ApiError) || e.status !== 401) throw e;
+
+    const jar = await cookies();
+    const refreshToken = jar.get(REFRESH_TOKEN_COOKIE)?.value;
+    if (!refreshToken) throw e;
+
+    const r = await refreshSession(refreshToken);
+    if (!r.ok) throw new ApiError(401, 'UNAUTHORIZED', null);
+
+    jar.set(ACCESS_TOKEN_COOKIE, r.accessToken, COOKIE);
+    jar.set(REFRESH_TOKEN_COOKIE, r.refreshToken, COOKIE);
+
+    return await fn();
+  }
+}
+`,
+
+    'app/api/proxy/[...path]/route.ts': `import { cookies } from 'next/headers';
+import { NextResponse, type NextRequest } from 'next/server';
+
+import {
+  captureApiError,
+  logApiError,
+} from '@/src/shared/api/observability';
+import { refreshSession } from '@/src/shared/api/refreshSession';
+
+const API_URL = process.env.API_URL ?? 'http://localhost:8080/api';
+const ACCESS_TOKEN_COOKIE = 'accessToken';
+const REFRESH_TOKEN_COOKIE = 'refreshToken';
+const LOCALE_COOKIE = 'NEXT_LOCALE';
+
+const COOKIE = {
+  httpOnly: true,
+  secure: process.env.COOKIE_SECURE === 'true',
+  sameSite: 'lax' as const,
+  path: '/',
+};
+
+const clearAuthCookies = (res: NextResponse) => {
+  res.cookies.set(ACCESS_TOKEN_COOKIE, '', { ...COOKIE, maxAge: 0 });
+  res.cookies.set(REFRESH_TOKEN_COOKIE, '', { ...COOKIE, maxAge: 0 });
+  return res;
+};
+
+const proxyRequest = async (
+  request: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+  method: string,
+) => {
+  const { path } = await ctx.params;
+  const apiPath = path.join('/');
+  const url = new URL(\`\${API_URL}/\${apiPath}\`);
+
+  request.nextUrl.searchParams.forEach((value, key) => {
+    url.searchParams.set(key, value);
+  });
+
+  const cookieStore = await cookies();
+  const accessToken = cookieStore.get(ACCESS_TOKEN_COOKIE)?.value;
+  const refreshToken = cookieStore.get(REFRESH_TOKEN_COOKIE)?.value;
+  const locale =
+    cookieStore.get(LOCALE_COOKIE)?.value ??
+    request.headers.get('Accept-Language') ??
+    undefined;
+
+  const headers: Record<string, string> = {};
+  if (accessToken) headers.Authorization = \`Bearer \${accessToken}\`;
+  if (locale) headers['Accept-Language'] = locale;
+
+  let body: BodyInit | undefined;
+  if (method !== 'GET' && method !== 'HEAD') {
+    const contentType = request.headers.get('Content-Type');
+    if (contentType?.includes('multipart/form-data')) {
+      body = await request.formData();
+    } else {
+      headers['Content-Type'] = 'application/json';
+      body = await request.text();
+    }
+  }
+
+  let response: Response;
+  try {
+    response = await fetch(url.toString(), { method, headers, body });
+  } catch (error) {
+    console.error(\`[PROXY] \${method} \${url.toString()} —\`, error);
+    return NextResponse.json(
+      {
+        result: 'ERROR',
+        data: null,
+        error: {
+          code: 'NETWORK_ERROR',
+          message: '서버에 연결할 수 없습니다.',
+        },
+      },
+      { status: 502 },
+    );
+  }
+
+  let data = await response.json();
+
+  // 401 → refresh 시도 (RT 가 있을 때만)
+  if (response.status === 401) {
+    if (!refreshToken) {
+      return clearAuthCookies(NextResponse.json(data, { status: 401 }));
+    }
+
+    const r = await refreshSession(refreshToken);
+
+    // refresh placeholder 가 본문 미구현이면 항상 ok:false
+    // → 쿠키 삭제 + 401 그대로 (clientFetch 가 /sign-in 으로 이동)
+    if (!r.ok) {
+      return clearAuthCookies(NextResponse.json(data, { status: 401 }));
+    }
+
+    // 새 AT 로 재시도
+    headers.Authorization = \`Bearer \${r.accessToken}\`;
+    const retry = await fetch(url.toString(), { method, headers, body });
+    data = await retry.json();
+
+    const res = NextResponse.json(data, { status: retry.status });
+    res.cookies.set(ACCESS_TOKEN_COOKIE, r.accessToken, COOKIE);
+    res.cookies.set(REFRESH_TOKEN_COOKIE, r.refreshToken, COOKIE);
+
+    if (!retry.ok) {
+      logApiError('PROXY', {
+        url: url.toString(),
+        method,
+        status: retry.status,
+        requestBody: typeof body === 'string' ? body : undefined,
+        responseBody: data,
+      });
+
+      captureApiError({
+        url: url.toString(),
+        apiPath,
+        method,
+        status: retry.status,
+        responseBody: data,
+      });
+    }
+
+    return res;
+  }
+
+  if (!response.ok) {
+    logApiError('PROXY', {
+      url: url.toString(),
+      method,
+      status: response.status,
+      requestBody: typeof body === 'string' ? body : undefined,
+      responseBody: data,
+    });
+
+    captureApiError({
+      url: url.toString(),
+      apiPath,
+      method,
+      status: response.status,
+      responseBody: data,
+    });
+  }
+
+  return NextResponse.json(data, { status: response.status });
+};
+
+export const GET = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'GET');
+
+export const POST = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'POST');
+
+export const PUT = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'PUT');
+
+export const PATCH = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'PATCH');
+
+export const DELETE = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'DELETE');
+`,
+  },
+};

package/src/create/plugins/index.js

@@ -1,7 +1,8 @@
 import { sentryPlugin } from './sentry.js';
 import { nextIntlPlugin } from './nextIntl.js';
+import { authJwtPlugin } from './authJwt.js';
 
-export const allPlugins = [sentryPlugin, nextIntlPlugin];
+export const allPlugins = [sentryPlugin, nextIntlPlugin, authJwtPlugin];
 
 export function getPluginChoices() {
   return allPlugins.map((p) => ({