sh-ui-cli 0.76.0 → 0.77.0

package/templates/nextjs-standalone/_arch/mes/app/layout.tsx

@@ -0,0 +1,16 @@
+import type { Metadata } from 'next';
+import { RootLayout } from '@/components/layouts/RootLayout';
+import './globals.css';
+
+export const metadata: Metadata = {
+  title: 'sh-ui app',
+  description: 'sh-ui 기반 앱 — metadata 를 변경하세요.',
+};
+
+export default function Layout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return <RootLayout>{children}</RootLayout>;
+}

package/templates/nextjs-standalone/_arch/mes/app/sign-in/page.tsx

@@ -0,0 +1 @@
+export { default } from '@/pages/sign-in';

package/templates/nextjs-standalone/_arch/mes/eslint.config.js

@@ -0,0 +1,137 @@
+import js from "@eslint/js"
+import pluginNext from "@next/eslint-plugin-next"
+import eslintConfigPrettier from "eslint-config-prettier"
+import boundaries from "eslint-plugin-boundaries"
+import checkFile from "eslint-plugin-check-file"
+import onlyWarn from "eslint-plugin-only-warn"
+import pluginReact from "eslint-plugin-react"
+import pluginReactHooks from "eslint-plugin-react-hooks"
+import globals from "globals"
+import tseslint from "typescript-eslint"
+
+export default [
+  {
+    ignores: [".next/**", "dist/**", "node_modules/**"],
+  },
+
+  // ── Base ──
+  js.configs.recommended,
+  eslintConfigPrettier,
+  ...tseslint.configs.recommended,
+  {
+    plugins: { onlyWarn },
+  },
+  {
+    rules: {
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
+      ],
+    },
+  },
+
+  // ── React + Next.js ──
+  {
+    ...pluginReact.configs.flat.recommended,
+    languageOptions: {
+      ...pluginReact.configs.flat.recommended.languageOptions,
+      globals: {
+        ...globals.serviceworker,
+      },
+    },
+  },
+  {
+    plugins: {
+      "@next/next": pluginNext,
+    },
+    rules: {
+      ...pluginNext.configs.recommended.rules,
+      ...pluginNext.configs["core-web-vitals"].rules,
+    },
+  },
+  {
+    plugins: {
+      "react-hooks": pluginReactHooks,
+    },
+    settings: { react: { version: "detect" } },
+    rules: {
+      ...pluginReactHooks.configs.recommended.rules,
+      "react/react-in-jsx-scope": "off",
+      "react/prop-types": "off",
+      "react/function-component-definition": [
+        "warn",
+        {
+          namedComponents: "function-declaration",
+          unnamedComponents: "arrow-function",
+        },
+      ],
+    },
+  },
+
+  // ── MES-arch boundaries ──
+  // 페이지 격리 + 단방향 의존:
+  //   - 각 `src/pages/<name>/` 는 자기완결 — 다른 페이지 import 금지
+  //   - 페이지/공용 컴포넌트는 hooks/lib 사용 OK, 반대 방향은 X
+  //   - app 라우트는 페이지/공용 모두 import 가능 (한 줄 위임)
+  {
+    plugins: { boundaries },
+    settings: {
+      "boundaries/elements": [
+        { type: "lib", pattern: ["src/lib/*"], mode: "folder" },
+        { type: "hooks", pattern: ["src/hooks"], mode: "folder" },
+        { type: "components", pattern: ["src/components/*"], mode: "folder" },
+        { type: "pages", pattern: ["src/pages/*"], mode: "folder" },
+        { type: "app", pattern: ["app"], mode: "folder" },
+      ],
+      "boundaries/ignore": ["**/*.test.*", "**/*.spec.*"],
+    },
+    rules: {
+      "boundaries/element-types": [
+        "warn",
+        {
+          default: "disallow",
+          rules: [
+            { from: "app", allow: ["pages", "components", "hooks", "lib"] },
+            // pages 끼리는 import 금지 — 페이지 격리 원칙
+            { from: "pages", allow: ["components", "hooks", "lib"] },
+            { from: "components", allow: ["components", "hooks", "lib"] },
+            { from: "hooks", allow: ["hooks", "lib"] },
+            { from: "lib", allow: ["lib"] },
+          ],
+        },
+      ],
+    },
+  },
+
+  // ── File naming ──
+  // .tsx = PASCAL_CASE (컴포넌트), .ts = CAMEL_CASE (유틸/스키마/훅)
+  {
+    plugins: { "check-file": checkFile },
+    rules: {
+      "check-file/filename-naming-convention": [
+        "error",
+        {
+          "**/components/**/*.tsx": "PASCAL_CASE",
+          "**/pages/**/components/**/*.tsx": "PASCAL_CASE",
+          "**/lib/**/*.ts": "CAMEL_CASE",
+          "**/hooks/**/*.ts": "CAMEL_CASE",
+        },
+        { ignoreMiddleExtensions: true },
+      ],
+    },
+  },
+  {
+    files: [
+      "**/index.tsx", "**/index.ts",
+      "**/layout.tsx", "**/page.tsx",
+      "**/error.tsx", "**/not-found.tsx",
+      "**/routing.ts", "**/navigation.ts", "**/request.ts",
+      // MES 페이지 concern 파일들
+      "**/pages/**/api.ts", "**/pages/**/schema.ts",
+      "**/pages/**/columns.ts", "**/pages/**/hooks.ts",
+    ],
+    rules: {
+      "check-file/filename-naming-convention": "off",
+    },
+  },
+]

package/templates/nextjs-standalone/_arch/mes/sh-ui.config.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://raw.githubusercontent.com/sanghyeonKim0201/sh-ui/live/packages/cli/sh-ui.schema.json",
+  "platform": "react",
+  "cssFramework": "plain",
+  "theme": {
+    "base": "neutral",
+    "radius": "md",
+    "mode": "light-dark"
+  },
+  "paths": {
+    "tokens": "src/lib/styles/tokens.css",
+    "cssEntry": "app/globals.css",
+    "styles": "src/lib/styles",
+    "components": "src/components/common",
+    "utils": "src/lib/utils/utils.ts"
+  },
+  "aliases": {
+    "components": "@/components/common",
+    "utils": "@/lib/utils/utils",
+    "ui": "@/components/common"
+  }
+}

package/templates/nextjs-standalone/_arch/mes/src/components/common/FallbackBoundary/index.tsx

@@ -0,0 +1,89 @@
+'use client';
+
+import {
+  Component,
+  type ComponentType,
+  type ErrorInfo,
+  type ReactNode,
+  Suspense,
+} from 'react';
+import { QueryErrorResetBoundary } from '@tanstack/react-query';
+
+export type ErrorFallbackProps = {
+  error: Error | null;
+  resetErrorBoundary: () => void;
+};
+
+type ErrorBoundaryProps = {
+  children: ReactNode;
+  fallback?: ComponentType<ErrorFallbackProps>;
+  onReset: () => void;
+  onError?: (error: Error, info: ErrorInfo) => void;
+};
+
+type ErrorBoundaryState = {
+  hasError: boolean;
+  error: Error | null;
+};
+
+class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  state: ErrorBoundaryState = { hasError: false, error: null };
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    this.props.onError?.(error, info);
+  }
+
+  resetErrorBoundary = () => {
+    this.props.onReset();
+    this.setState({ hasError: false, error: null });
+  };
+
+  render() {
+    const { hasError, error } = this.state;
+    const { children, fallback: Fallback } = this.props;
+
+    if (hasError && Fallback) {
+      return (
+        <Fallback error={error} resetErrorBoundary={this.resetErrorBoundary} />
+      );
+    }
+
+    return children;
+  }
+}
+
+type FallbackBoundaryProps = {
+  children: ReactNode;
+  errorFallback?: ComponentType<ErrorFallbackProps>;
+  suspenseFallback?: ReactNode;
+  onError?: (error: Error, info: ErrorInfo) => void;
+};
+
+/**
+ * Suspense + ErrorBoundary 합성. React Query 의 reset 신호에 맞춰
+ * `errorFallback` 의 `resetErrorBoundary` 가 쿼리까지 함께 리셋한다.
+ */
+export function FallbackBoundary({
+  children,
+  errorFallback,
+  suspenseFallback,
+  onError,
+}: FallbackBoundaryProps) {
+  return (
+    <QueryErrorResetBoundary>
+      {({ reset }) => (
+        <ErrorBoundary
+          onReset={reset}
+          fallback={errorFallback}
+          onError={onError}
+        >
+          <Suspense fallback={suspenseFallback}>{children}</Suspense>
+        </ErrorBoundary>
+      )}
+    </QueryErrorResetBoundary>
+  );
+}

package/templates/nextjs-standalone/_arch/mes/src/components/common/PrefetchBoundary/index.tsx

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+
+import {
+  dehydrate,
+  type FetchQueryOptions,
+  HydrationBoundary,
+} from '@tanstack/react-query';
+
+import { getQueryClient } from '@/lib/utils/getQueryClient';
+
+export type FetchOptions = Pick<FetchQueryOptions, 'queryKey' | 'queryFn'>;
+
+type Props = {
+  fetchOptions?: FetchOptions[] | FetchOptions | null;
+  children: ReactNode;
+};
+
+/**
+ * RSC 에서 prefetch 를 끝낸 뒤 dehydrated state 로 클라이언트에 hydrate.
+ * 단일/배열 둘 다 받는다.
+ */
+export async function PrefetchBoundary({ fetchOptions, children }: Props) {
+  const queryClient = getQueryClient();
+
+  if (fetchOptions) {
+    const list = Array.isArray(fetchOptions) ? fetchOptions : [fetchOptions];
+    await Promise.all(list.map((opt) => queryClient.prefetchQuery(opt)));
+  }
+
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      {children}
+    </HydrationBoundary>
+  );
+}

package/templates/nextjs-standalone/_arch/mes/src/components/layouts/RootLayout.tsx

@@ -0,0 +1,13 @@
+import { GlobalProvider } from '@/components/providers';
+
+export function RootLayout({ children }: { children: React.ReactNode }) {
+  // `lang` 은 앱의 주 언어. 영어 등 다른 언어 우선이면 'en' 으로 바꾸거나
+  // next-intl 플러그인을 활성화해 라우트 기반 자동 분기로 전환하세요.
+  return (
+    <html lang='ko' suppressHydrationWarning>
+      <body>
+        <GlobalProvider>{children}</GlobalProvider>
+      </body>
+    </html>
+  );
+}

package/templates/nextjs-standalone/_arch/mes/src/components/providers/GlobalProvider/index.tsx

@@ -0,0 +1,23 @@
+import type { ReactNode } from 'react';
+import { Toaster } from 'sonner';
+
+import { QueryClientProvider } from '../tanstack/QueryClientProvider';
+import { TanstackDevtoolsProvider } from '../tanstack/TanstackDevtoolsProvider';
+import { ThemeProvider } from '../theme/ThemeProvider';
+
+interface GlobalProviderProps {
+  children: ReactNode;
+}
+
+export function GlobalProvider({ children }: GlobalProviderProps) {
+  return (
+    <ThemeProvider>
+      <QueryClientProvider>
+        <TanstackDevtoolsProvider>
+          <Toaster />
+          {children}
+        </TanstackDevtoolsProvider>
+      </QueryClientProvider>
+    </ThemeProvider>
+  );
+}

package/templates/nextjs-standalone/_arch/mes/src/components/providers/index.tsx

@@ -0,0 +1 @@
+export { GlobalProvider } from './GlobalProvider';

package/templates/nextjs-standalone/_arch/mes/src/components/providers/tanstack/QueryClientProvider.tsx

@@ -0,0 +1,14 @@
+'use client';
+
+import { QueryClientProvider as TanstackQueryClientProvider } from '@tanstack/react-query';
+import type { ReactNode } from 'react';
+
+import { getBrowserQueryClient } from '@/lib/api/queryClient';
+
+export function QueryClientProvider({ children }: { children: ReactNode }) {
+  return (
+    <TanstackQueryClientProvider client={getBrowserQueryClient()}>
+      {children}
+    </TanstackQueryClientProvider>
+  );
+}

package/templates/nextjs-standalone/_arch/mes/src/components/providers/tanstack/TanstackDevtoolsProvider.tsx

@@ -0,0 +1,13 @@
+'use client';
+
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
+import type { ReactNode } from 'react';
+
+export function TanstackDevtoolsProvider({ children }: { children: ReactNode }) {
+  return (
+    <>
+      {children}
+      <ReactQueryDevtools initialIsOpen={false} />
+    </>
+  );
+}

package/templates/nextjs-standalone/_arch/mes/src/components/providers/theme/ThemeProvider.tsx

@@ -0,0 +1,27 @@
+'use client';
+
+import { ThemeProvider as NextThemesProvider } from 'next-themes';
+import type { ReactNode } from 'react';
+
+/**
+ * 다크/라이트 테마 — next-themes ThemeProvider 를 wrap.
+ *
+ * - `attribute='class'` — `<html class="dark">` 토글 (Tailwind dark variant 와 호환)
+ * - `defaultTheme='system'` + `enableSystem` — OS 설정에 자동 동기화. light/dark 만
+ *   노출하려면 `enableSystem` 을 false 로
+ * - `disableTransitionOnChange` — 토글 순간 transition 깜빡임 차단
+ *
+ * useTheme 는 next-themes 에서 직접 import: `import { useTheme } from 'next-themes'`
+ */
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  return (
+    <NextThemesProvider
+      attribute='class'
+      defaultTheme='system'
+      enableSystem
+      disableTransitionOnChange
+    >
+      {children}
+    </NextThemesProvider>
+  );
+}

package/templates/nextjs-standalone/_arch/mes/src/hooks/useAppMutation.ts

@@ -0,0 +1,59 @@
+import {
+  useMutation,
+  type UseMutationOptions,
+  type DefaultError,
+} from '@tanstack/react-query';
+import { toast } from 'sonner';
+
+import { ApiError } from '@/lib/api/error';
+import { resolveErrorMessage } from '@/lib/api/errorMessages';
+
+type AppMutationOptions<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TContext = unknown,
+> = UseMutationOptions<TData, TError, TVariables, TContext> & {
+  /** ApiError 가 아니거나 mapping 에 없을 때의 fallback 메시지. */
+  errorMessage?: string;
+  /** false 면 toast 띄우지 않음. */
+  showErrorToast?: boolean;
+};
+
+/**
+ * useMutation 래퍼 — 에러 발생 시 `resolveErrorMessage` 를 통해 안전한
+ * 사용자 facing 메시지를 toast 로 띄운다. backend 가 보낸 raw 메시지를 그대로
+ * 띄우지 않고 `errorMessages.ts` 의 mapping 을 우선 사용해 일관된 사용자
+ * 경험과 i18n 친화성을 확보.
+ *
+ * showErrorToast: false 로 자동 toast 끌 수 있고, errorMessage 로 fallback 지정.
+ */
+export const useAppMutation = <
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TContext = unknown,
+>(
+  options: AppMutationOptions<TData, TError, TVariables, TContext>,
+) => {
+  const { errorMessage, showErrorToast = true, onError, ...rest } = options;
+
+  return useMutation({
+    ...rest,
+    onError: (...args) => {
+      onError?.(...args);
+
+      if (!showErrorToast) return;
+
+      const [error] = args;
+      const message = resolveErrorMessage(error, errorMessage);
+
+      if (message) {
+        toast.error(message);
+      }
+    },
+  });
+};
+
+// re-export ApiError 타입을 쓰는 사용처 편의용 (선택).
+export type { ApiError };

package/templates/nextjs-standalone/_arch/mes/src/lib/api/apiTypes.ts

@@ -0,0 +1,21 @@
+/** 공통 API 에러 형식 */
+export type ApiErrorBody = {
+  message: string;
+  code: string;
+};
+
+/** 백엔드 공통 응답 래퍼 */
+export type ApiResponse<TData = unknown, TError = ApiErrorBody> = {
+  result: 'SUCCESS' | 'ERROR';
+  data: TData;
+  error: TError | null;
+};
+
+/** 페이지네이션 응답 래퍼 */
+export type PaginatedData<T> = {
+  content: T[];
+  totalItems: number;
+  offset: number;
+  limit: number;
+  hasNext: boolean;
+};

package/templates/nextjs-standalone/_arch/mes/src/lib/api/clientFetch.ts

@@ -0,0 +1,40 @@
+'use client';
+
+import type { ApiResponse } from './apiTypes';
+import { ApiError } from './error';
+
+const PROXY_BASE = '/api/proxy';
+
+export async function clientFetch<T>(
+  path: string,
+  init: RequestInit = {},
+): Promise<T> {
+  const url = `${PROXY_BASE}${path.startsWith('/') ? path : `/${path}`}`;
+
+  const res = await fetch(url, {
+    ...init,
+    headers: {
+      'Content-Type': 'application/json',
+      ...(init.headers as Record<string, string> | undefined),
+    },
+    credentials: 'include',
+  });
+
+  const body = (await res.json()) as ApiResponse<T>;
+
+  if (res.status === 401) {
+    // 이미 sign-in 페이지면 redirect 루프 방지.
+    // next-intl 활성 시 path 가 `/ko/sign-in` 형태가 되므로 regex 로 match.
+    if (typeof window !== 'undefined' && !/\/sign-in(\/|$)/.test(window.location.pathname)) {
+      // /sign-in 으로만 보내면 middleware (next-intl 활성 시) 가 default locale 을 prefix 추가.
+      window.location.href = '/sign-in';
+    }
+    throw new ApiError(401, body.error?.code ?? 'UNAUTHORIZED', body.error);
+  }
+
+  if (!res.ok || body.result === 'ERROR') {
+    throw new ApiError(res.status, body.error?.code ?? '', body.error);
+  }
+
+  return body.data;
+}

package/templates/nextjs-standalone/_arch/mes/src/lib/api/error.ts

@@ -0,0 +1,12 @@
+import type { ApiErrorBody } from './apiTypes';
+
+export class ApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly code: string,
+    public readonly data: ApiErrorBody | null,
+  ) {
+    super(data?.message ?? `API 요청 실패 (${status})`);
+    this.name = 'ApiError';
+  }
+}

package/templates/nextjs-standalone/_arch/mes/src/lib/api/errorMessages.ts

@@ -0,0 +1,37 @@
+import { ApiError } from './error';
+
+/**
+ * 에러 코드 → 사용자 facing 메시지 mapping.
+ *
+ * 백엔드가 보내는 raw `error.message` 를 그대로 toast 로 띄우면 i18n 어긋나거나
+ * 내부 노출이 될 수 있어, frontend 가 정의한 안전한 메시지로 변환하는 게 권장.
+ * 코드별로 명시 안 된 경우 `error.data.message` (backend 메시지) → fallback.
+ *
+ * 사용자 프로젝트에서 자유롭게 추가/수정. next-intl 활성 시엔 `useTranslations`
+ * 와 결합해 hook 형태로 변환 가능 (이 파일은 RSC/CSR 양쪽 호환을 위해 module).
+ */
+export const ERROR_MESSAGES: Record<string, string> = {
+  UNAUTHORIZED: '로그인이 필요합니다.',
+  FORBIDDEN: '접근 권한이 없습니다.',
+  NOT_FOUND: '요청한 리소스를 찾을 수 없습니다.',
+  NETWORK_ERROR: '서버에 연결할 수 없습니다. 잠시 후 다시 시도해 주세요.',
+  // 사용자 정의 코드를 여기에 추가하세요.
+};
+
+const DEFAULT_FALLBACK = '일시적인 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.';
+
+/**
+ * 에러 → 사용자 facing 메시지 결정.
+ *  1. ApiError + 코드가 ERROR_MESSAGES 에 있으면 그 메시지
+ *  2. ApiError 의 backend `data.message` (있으면)
+ *  3. 호출자의 fallback
+ *  4. 글로벌 DEFAULT_FALLBACK
+ */
+export function resolveErrorMessage(error: unknown, fallback?: string): string {
+  if (error instanceof ApiError) {
+    const mapped = ERROR_MESSAGES[error.code];
+    if (mapped) return mapped;
+    if (error.data?.message) return error.data.message;
+  }
+  return fallback ?? DEFAULT_FALLBACK;
+}

package/templates/nextjs-standalone/_arch/mes/src/lib/api/http.ts

@@ -0,0 +1,13 @@
+import { clientFetch } from './clientFetch';
+import { serverFetch } from './serverFetch';
+
+/**
+ * isomorphic 진입점.
+ * RSC/서버에서는 백엔드로 직통, 브라우저에서는 /api/proxy 경유.
+ * API 함수는 한 번만 작성하고 환경 분기는 여기서 처리한다.
+ */
+export function http<T>(path: string, init?: RequestInit): Promise<T> {
+  return typeof window === 'undefined'
+    ? serverFetch<T>(path, init)
+    : clientFetch<T>(path, init);
+}

package/templates/nextjs-standalone/_arch/mes/src/lib/api/observability.ts

@@ -0,0 +1,20 @@
+type ApiCaptureParams = {
+  url: string;
+  apiPath: string;
+  method: string;
+  status: number | undefined;
+  responseBody?: unknown;
+};
+
+type ApiLogParams = {
+  url: string;
+  method: string;
+  status: number | undefined;
+  requestHeaders?: Record<string, string | undefined>;
+  requestBody?: unknown;
+  responseBody?: unknown;
+};
+
+export const captureApiError = (_params: ApiCaptureParams): void => {};
+
+export const logApiError = (_prefix: string, _params: ApiLogParams): void => {};

package/templates/nextjs-standalone/_arch/mes/src/lib/api/queryClient.ts

@@ -0,0 +1,30 @@
+import {
+  QueryClient,
+  defaultShouldDehydrateQuery,
+  isServer,
+} from '@tanstack/react-query';
+import { cache } from 'react';
+
+function makeQueryClient(): QueryClient {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000,
+        retry: 1,
+      },
+      dehydrate: {
+        shouldDehydrateQuery: (q) =>
+          defaultShouldDehydrateQuery(q) || q.state.status === 'pending',
+      },
+    },
+  });
+}
+
+export const getServerQueryClient = cache(makeQueryClient);
+
+let browserQueryClient: QueryClient | undefined;
+
+export function getBrowserQueryClient(): QueryClient {
+  if (isServer) return makeQueryClient();
+  return (browserQueryClient ??= makeQueryClient());
+}