sh-ui-cli 0.74.1 → 0.76.0

package/bin/sh-ui.mjs

@@ -35,7 +35,7 @@ const usage = `사용법:
                                    (--apply 로 실제 적용)
   sh-ui mcp                        MCP 서버(stdio) 시작 — IDE-내 AI용
   sh-ui mcp init --client <name>   IDE MCP 설정 파일에 sh-ui 엔트리 자동 추가
-                                   (claude-code | cursor | claude-desktop)
+                                   (claude-code | cursor | claude-desktop | codex)
   옵션:
     --skip-install                 (add, rename-app) 외부 패키지 자동 설치 생략
     --diff                         (add) 파일을 쓰지 않고 변경 내역만 출력

package/data/changelog/versions.json

@@ -2,6 +2,32 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.76.0",
+      "date": "2026-05-11",
+      "title": "minor — `sh-ui mcp init` 가 codex CLI 도 자동 등록",
+      "type": "minor",
+      "highlights": [
+        "**`sh-ui mcp init --client codex` 신규 지원** — `~/.codex/config.toml` 의 `[mcp_servers.sh-ui]` 섹션을 자동 upsert. 이제 codex 사용자도 한 번에 sh-ui MCP 등록.",
+        "**TOML 텍스트 기반 머지** — 다른 섹션·주석·공백을 그대로 보존. `[mcp_servers.sh-ui]` 와 그 하위(`.env` 등)만 교체 후 새 블록을 append. 멱등 보장(연속 호출 결과 동일).",
+        "**inline-table 정의는 명시적 에러** — 기존 `[mcp_servers]` 부모 섹션 안에 `sh-ui = { ... }` 형태로 정의돼 있으면 자동 갱신 대신 명확한 메시지로 수동 정리 안내. 사용자 config 손상 방지.",
+        "claude-code / cursor / claude-desktop 동작은 변화 없음."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.76.0"
+    },
+    {
+      "version": "0.75.0",
+      "date": "2026-05-11",
+      "title": "minor — 슬롯 패턴 `render` 로 통일 (asChild 제거)",
+      "type": "minor",
+      "highlights": [
+        "**모든 슬롯 패턴이 `render` prop 으로 통일** — Base UI 가 표준으로 사용하는 패턴. 이전엔 Base UI 기반 컴포넌트(Dialog/Popover/Select/DropdownMenu/Accordion/Combobox/Tabs)는 `render`, sh-ui 자체 컴포넌트(Sidebar/Breadcrumb)는 `asChild` 로 혼재. 이번에 후자도 `render` 로 통일해 사용자 mental model 단순화.",
+        "**BreadcrumbLink 에 `render` prop 신규 추가** — 이전엔 슬롯 패턴 자체가 없어 Next Link 와 결합하려면 className 만 수동 복사해야 했음. 이제 `<BreadcrumbLink render={<Link href='/projects'>Projects</Link>} />` 정석.",
+        "**SidebarMenuButton·SidebarMenuSubButton 의 `asChild` 제거 → `render` 로 마이그레이션** — children 으로 자식 element 넘기던 패턴 대신 `render` prop. cloneElement 로 props/className/ref 자동 머지 동작은 동일. apps/docs 의 app-sidebar / sidebar-toc demo / sidebar API 문서까지 일괄 마이그.",
+        "**summary + JSDoc 갱신** — sidebar / breadcrumb summary 에 render prop 사용 패턴 명시. MCP `sh_ui_list_components` 와 `sh_ui_get_component` 둘 다 일관."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.75.0"
+    },
     {
       "version": "0.74.1",
       "date": "2026-05-11",

package/data/registry/react/components/breadcrumb/index.module.tsx

@@ -59,17 +59,42 @@ export const BreadcrumbItem = React.forwardRef<
 
 /* ───────── Link ───────── */
 
-/** 상위 단계로 이동하는 링크. 라우터 사용 시 `asChild` 패턴 대신 직접 `<a>` 속성으로 전달. */
+export interface BreadcrumbLinkProps
+  extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  /**
+   * 다른 anchor 컴포넌트(예: Next.js `Link`)로 대체. sh-ui 의 모든 슬롯
+   * 패턴은 `render` 로 통일 (Base UI 표준).
+   *
+   *   <BreadcrumbLink render={<Link href='/projects'>Projects</Link>} />
+   */
+  render?: React.ReactElement;
+}
+
+/** 상위 단계로 이동하는 링크. `render` prop 으로 다른 엘리먼트 슬롯 가능. */
 export const BreadcrumbLink = React.forwardRef<
   HTMLAnchorElement,
-  React.AnchorHTMLAttributes<HTMLAnchorElement>
->(function BreadcrumbLink({ className, ...props }, ref) {
+  BreadcrumbLinkProps
+>(function BreadcrumbLink({ className, render, children, ...props }, ref) {
+  const mergedClass = cn(styles.breadcrumb__link, className);
+  if (render && React.isValidElement(render)) {
+    const child = render as React.ReactElement<{
+      className?: string;
+      children?: React.ReactNode;
+    }>;
+    return React.cloneElement(
+      child,
+      {
+        ref,
+        className: cn(child.props.className, mergedClass),
+        ...props,
+      } as Record<string, unknown>,
+      children ?? child.props.children,
+    );
+  }
   return (
-    <a
-      ref={ref}
-      className={cn(styles.breadcrumb__link, className)}
-      {...props}
-    />
+    <a ref={ref} className={mergedClass} {...props}>
+      {children}
+    </a>
   );
 });
 

package/data/registry/react/components/breadcrumb/index.tailwind.tsx

@@ -45,19 +45,44 @@ export const BreadcrumbItem = React.forwardRef<
   );
 });
 
+export interface BreadcrumbLinkProps
+  extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  /**
+   * 다른 anchor 컴포넌트(예: Next.js `Link`)로 대체. anchor 중첩 방지 + 라우터
+   * 결합용. sh-ui 의 모든 슬롯 패턴은 `render` 로 통일 (Base UI 표준).
+   *
+   *   <BreadcrumbLink render={<Link href='/projects'>Projects</Link>} />
+   */
+  render?: React.ReactElement;
+}
+
 export const BreadcrumbLink = React.forwardRef<
   HTMLAnchorElement,
-  React.AnchorHTMLAttributes<HTMLAnchorElement>
->(function BreadcrumbLink({ className, ...props }, ref) {
+  BreadcrumbLinkProps
+>(function BreadcrumbLink({ className, render, children, ...props }, ref) {
+  const mergedClass = cn(
+    "text-foreground-muted no-underline rounded-[calc(var(--radius)-2px)] px-0.5 transition-colors duration-[var(--duration-fast)] hover:text-foreground hover:underline hover:underline-offset-[3px] focus-visible:outline-[length:var(--border-width-strong)] focus-visible:outline-ring focus-visible:outline-offset-2 motion-reduce:transition-none",
+    className,
+  );
+  if (render && React.isValidElement(render)) {
+    const child = render as React.ReactElement<{
+      className?: string;
+      children?: React.ReactNode;
+    }>;
+    return React.cloneElement(
+      child,
+      {
+        ref,
+        className: cn(child.props.className, mergedClass),
+        ...props,
+      } as Record<string, unknown>,
+      children ?? child.props.children,
+    );
+  }
   return (
-    <a
-      ref={ref}
-      className={cn(
-        "text-foreground-muted no-underline rounded-[calc(var(--radius)-2px)] px-0.5 transition-colors duration-[var(--duration-fast)] hover:text-foreground hover:underline hover:underline-offset-[3px] focus-visible:outline-[length:var(--border-width-strong)] focus-visible:outline-ring focus-visible:outline-offset-2 motion-reduce:transition-none",
-        className,
-      )}
-      {...props}
-    />
+    <a ref={ref} className={mergedClass} {...props}>
+      {children}
+    </a>
   );
 });
 

package/data/registry/react/components/breadcrumb/index.tsx

@@ -59,17 +59,45 @@ export const BreadcrumbItem = React.forwardRef<
 
 /* ───────── Link ───────── */
 
-/** 상위 단계로 이동하는 링크. 라우터 사용 시 `asChild` 패턴 대신 직접 `<a>` 속성으로 전달. */
+export interface BreadcrumbLinkProps
+  extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  /**
+   * 다른 anchor 컴포넌트(예: Next.js `Link`)로 대체. 자체로 `<a>` 를 렌더
+   * 하므로 자식으로 또 다른 `<a>` 를 넣으면 anchor 중첩(invalid HTML). 정석은
+   * Base UI 패턴과 동일한 `render` prop:
+   *
+   *   <BreadcrumbLink render={<Link href='/projects'>Projects</Link>} />
+   *
+   * sh-ui 의 모든 슬롯 패턴은 `render` 로 통일 (Base UI 표준 따름).
+   */
+  render?: React.ReactElement;
+}
+
+/** 상위 단계로 이동하는 링크. `render` prop 으로 다른 엘리먼트(Next Link 등) 슬롯 가능. */
 export const BreadcrumbLink = React.forwardRef<
   HTMLAnchorElement,
-  React.AnchorHTMLAttributes<HTMLAnchorElement>
->(function BreadcrumbLink({ className, ...props }, ref) {
+  BreadcrumbLinkProps
+>(function BreadcrumbLink({ className, render, children, ...props }, ref) {
+  const mergedClass = cn("sh-ui-breadcrumb__link", className);
+  if (render && React.isValidElement(render)) {
+    const child = render as React.ReactElement<{
+      className?: string;
+      children?: React.ReactNode;
+    }>;
+    return React.cloneElement(
+      child,
+      {
+        ref,
+        className: cn(child.props.className, mergedClass),
+        ...props,
+      } as Record<string, unknown>,
+      children ?? child.props.children,
+    );
+  }
   return (
-    <a
-      ref={ref}
-      className={cn("sh-ui-breadcrumb__link", className)}
-      {...props}
-    />
+    <a ref={ref} className={mergedClass} {...props}>
+      {children}
+    </a>
   );
 });
 

package/data/registry/react/components/sidebar/index.module.tsx

@@ -591,12 +591,13 @@ export interface SidebarMenuButtonProps extends React.ButtonHTMLAttributes<HTMLB
    */
   size?: "sm" | "md" | "lg";
   /**
-   * Radix asChild 패턴. children에 `<a>` 등 다른 요소를 넘겨 button 스타일만 입힐 때 사용.
-   * Next.js Link와 결합 시 유용 (`<SidebarMenuButton asChild><Link href=...>`).
+   * 다른 엘리먼트(예: Next.js `Link`)로 대체. 자체로 `<button>` 을 렌더하므로
+   * 자식으로 또 다른 button/anchor 를 넣지 말 것. sh-ui 의 모든 슬롯 패턴은
+   * `render` 로 통일 (Base UI 표준).
    *
-   * @default false
+   *   <SidebarMenuButton render={<Link href='/'>홈</Link>} />
    */
-  asChild?: boolean;
+  render?: React.ReactElement;
   /**
    * `SidebarTOC` 안에서 활성 섹션 id를 자동 동기화. 이 값과 TOC active id가 일치하면
    * `isActive`가 자동으로 `true`가 된다.
@@ -610,12 +611,13 @@ export interface SidebarMenuButtonProps extends React.ButtonHTMLAttributes<HTMLB
 }
 
 /**
- * 메뉴 한 줄을 누를 수 있는 버튼. `asChild`로 `<a>` 등 다른 요소에 스타일만 입힐 수 있고,
- * `sectionId`(SidebarTOC 활성 동기화) / `panelId`(SidebarPanel 토글)를 지정해 활성 상태를 자동 결정한다.
+ * 메뉴 한 줄을 누를 수 있는 버튼. `render` prop 으로 `<a>` 등 다른 엘리먼트로
+ * 슬롯 가능. `sectionId`(SidebarTOC 활성 동기화) / `panelId`(SidebarPanel 토글)를
+ * 지정해 활성 상태를 자동 결정한다.
  */
 export const SidebarMenuButton = React.forwardRef<HTMLButtonElement, SidebarMenuButtonProps>(
   function SidebarMenuButton(
-    { className, isActive, size = "md", asChild, sectionId, panelId, onClick, children, ...props },
+    { className, isActive, size = "md", render, sectionId, panelId, onClick, children, ...props },
     ref
   ) {
     const tocActive = useTOCActiveId();
@@ -640,15 +642,19 @@ export const SidebarMenuButton = React.forwardRef<HTMLButtonElement, SidebarMenu
       styles[`sidebar__menu-button--${size}`],
       className);
 
-    if (asChild && React.isValidElement(children)) {
-      const child = children as React.ReactElement<Record<string, unknown>>;
-      const merged: Record<string, unknown> = {
-        ...props,
-        onClick: handleClick,
-        className: cn((child.props.className as string) || "", cls),
-        "data-active": resolvedIsActive || undefined,
-      };
-      return React.cloneElement(child, merged);
+    if (render && React.isValidElement(render)) {
+      const child = render as React.ReactElement<{ className?: string; children?: React.ReactNode }>;
+      return React.cloneElement(
+        child,
+        {
+          ref,
+          ...props,
+          onClick: handleClick,
+          className: cn(child.props.className, cls),
+          "data-active": resolvedIsActive || undefined,
+        } as Record<string, unknown>,
+        children ?? child.props.children,
+      );
     }
 
     return (
@@ -697,18 +703,17 @@ export interface SidebarMenuSubButtonProps extends React.AnchorHTMLAttributes<HT
    */
   size?: "sm" | "md";
   /**
-   * Radix asChild 패턴. children에 다른 anchor 컴포넌트(예: Next.js Link)를 넘길 때 사용.
-   * @default false
+   * 다른 anchor 컴포넌트(예: Next.js `Link`)로 대체. sh-ui 의 슬롯 패턴은 `render` 로 통일.
    */
-  asChild?: boolean;
+  render?: React.ReactElement;
   /** `SidebarTOC`의 활성 섹션 id 자동 동기화. 일치하면 `isActive`가 자동으로 `true`. */
   sectionId?: string;
 }
 
-/** 서브 메뉴 항목 내부의 링크(`<a>`). `sectionId`로 SidebarTOC 활성 상태와 연동. */
+/** 서브 메뉴 항목 내부의 링크. `render` prop 으로 다른 엘리먼트 슬롯 가능. `sectionId`로 TOC 활성 연동. */
 export const SidebarMenuSubButton = React.forwardRef<HTMLAnchorElement, SidebarMenuSubButtonProps>(
   function SidebarMenuSubButton(
-    { className, isActive, size = "md", asChild, sectionId, children, ...props },
+    { className, isActive, size = "md", render, sectionId, children, ...props },
     ref
   ) {
     const tocActive = useTOCActiveId();
@@ -718,14 +723,18 @@ export const SidebarMenuSubButton = React.forwardRef<HTMLAnchorElement, SidebarM
       styles[`sidebar__menu-sub-button--${size}`],
       className);
 
-    if (asChild && React.isValidElement(children)) {
-      const child = children as React.ReactElement<Record<string, unknown>>;
-      const merged: Record<string, unknown> = {
-        ...props,
-        className: cn((child.props.className as string) || "", cls),
-        "data-active": resolvedIsActive || undefined,
-      };
-      return React.cloneElement(child, merged);
+    if (render && React.isValidElement(render)) {
+      const child = render as React.ReactElement<{ className?: string; children?: React.ReactNode }>;
+      return React.cloneElement(
+        child,
+        {
+          ref,
+          ...props,
+          className: cn(child.props.className, cls),
+          "data-active": resolvedIsActive || undefined,
+        } as Record<string, unknown>,
+        children ?? child.props.children,
+      );
     }
 
     return (
@@ -930,9 +939,7 @@ export function SidebarCollapsibleContent({ children }: { children: React.ReactN
  *   <SidebarTOC sectionIds={["intro", "install", "usage"]}>
  *     <SidebarMenu>
  *       <SidebarMenuItem>
- *         <SidebarMenuButton sectionId="intro" asChild>
- *           <a href="#intro">Intro</a>
- *         </SidebarMenuButton>
+ *         <SidebarMenuButton sectionId="intro" render={<a href="#intro">Intro</a>} />
  *       </SidebarMenuItem>
  *       ...
  *     </SidebarMenu>

package/data/registry/react/components/sidebar/index.tailwind.tsx

@@ -350,7 +350,12 @@ export function SidebarMenuItem({ className, ...props }: React.HTMLAttributes<HT
 export interface SidebarMenuButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   isActive?: boolean;
   size?: "sm" | "md" | "lg";
-  asChild?: boolean;
+  /**
+   * 다른 엘리먼트(예: Next.js `Link`)로 대체. sh-ui 의 슬롯 패턴은 `render` 로 통일.
+   *
+   *   <SidebarMenuButton render={<Link href='/'>홈</Link>} />
+   */
+  render?: React.ReactElement;
   sectionId?: string;
   panelId?: string;
 }
@@ -365,7 +370,7 @@ const menuButtonSize = {
 };
 
 export const SidebarMenuButton = React.forwardRef<HTMLButtonElement, SidebarMenuButtonProps>(
-  function SidebarMenuButton({ className, isActive, size = "md", asChild, sectionId, panelId, onClick, children, ...props }, ref) {
+  function SidebarMenuButton({ className, isActive, size = "md", render, sectionId, panelId, onClick, children, ...props }, ref) {
     const tocActive = useTOCActiveId();
     const ctx = React.useContext(SidebarContext);
     const panelActive = panelId != null && ctx?.activePanel === panelId;
@@ -378,15 +383,19 @@ export const SidebarMenuButton = React.forwardRef<HTMLButtonElement, SidebarMenu
 
     const cls = cn(menuButtonBase, menuButtonSize[size], className);
 
-    if (asChild && React.isValidElement(children)) {
-      const child = children as React.ReactElement<Record<string, unknown>>;
-      const merged: Record<string, unknown> = {
-        ...props,
-        onClick: handleClick,
-        className: cn((child.props.className as string) || "", cls),
-        "data-active": resolvedIsActive || undefined,
-      };
-      return React.cloneElement(child, merged);
+    if (render && React.isValidElement(render)) {
+      const child = render as React.ReactElement<{ className?: string; children?: React.ReactNode }>;
+      return React.cloneElement(
+        child,
+        {
+          ref,
+          ...props,
+          onClick: handleClick,
+          className: cn(child.props.className, cls),
+          "data-active": resolvedIsActive || undefined,
+        } as Record<string, unknown>,
+        children ?? child.props.children,
+      );
     }
 
     return (
@@ -414,7 +423,10 @@ export function SidebarMenuSubItem({ className, ...props }: React.HTMLAttributes
 export interface SidebarMenuSubButtonProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
   isActive?: boolean;
   size?: "sm" | "md";
-  asChild?: boolean;
+  /**
+   * 다른 anchor 컴포넌트(예: Next.js `Link`)로 대체. sh-ui 의 슬롯 패턴은 `render` 로 통일.
+   */
+  render?: React.ReactElement;
   sectionId?: string;
 }
 
@@ -422,19 +434,23 @@ const menuSubButtonBase =
   "flex items-center gap-[var(--space-2)] h-7 px-[var(--space-2)] rounded-[calc(var(--radius)-2px)] text-[0.8125rem] text-[var(--sidebar-fg)] no-underline transition-[background-color,color] duration-[var(--duration-fast)] min-w-0 [&>span]:flex-1 [&>span]:min-w-0 [&>span]:overflow-hidden [&>span]:[text-overflow:ellipsis] [&>span]:whitespace-nowrap hover:bg-[var(--sidebar-accent)] hover:text-[var(--sidebar-accent-fg)] data-[active]:bg-primary data-[active]:text-primary-foreground data-[active]:font-semibold data-[active]:hover:bg-primary-hover motion-reduce:transition-none";
 
 export const SidebarMenuSubButton = React.forwardRef<HTMLAnchorElement, SidebarMenuSubButtonProps>(
-  function SidebarMenuSubButton({ className, isActive, size = "md", asChild, sectionId, children, ...props }, ref) {
+  function SidebarMenuSubButton({ className, isActive, size = "md", render, sectionId, children, ...props }, ref) {
     const tocActive = useTOCActiveId();
     const resolvedIsActive = isActive ?? (sectionId != null ? tocActive === sectionId : undefined);
     const cls = cn(menuSubButtonBase, size === "sm" && "text-[length:var(--text-xs)]", className);
 
-    if (asChild && React.isValidElement(children)) {
-      const child = children as React.ReactElement<Record<string, unknown>>;
-      const merged: Record<string, unknown> = {
-        ...props,
-        className: cn((child.props.className as string) || "", cls),
-        "data-active": resolvedIsActive || undefined,
-      };
-      return React.cloneElement(child, merged);
+    if (render && React.isValidElement(render)) {
+      const child = render as React.ReactElement<{ className?: string; children?: React.ReactNode }>;
+      return React.cloneElement(
+        child,
+        {
+          ref,
+          ...props,
+          className: cn(child.props.className, cls),
+          "data-active": resolvedIsActive || undefined,
+        } as Record<string, unknown>,
+        children ?? child.props.children,
+      );
     }
 
     return <a ref={ref} className={cls} data-active={resolvedIsActive || undefined} {...props}>{children}</a>;

package/data/registry/react/components/sidebar/index.tsx

@@ -591,12 +591,13 @@ export interface SidebarMenuButtonProps extends React.ButtonHTMLAttributes<HTMLB
    */
   size?: "sm" | "md" | "lg";
   /**
-   * Radix asChild 패턴. children에 `<a>` 등 다른 요소를 넘겨 button 스타일만 입힐 때 사용.
-   * Next.js Link와 결합 시 유용 (`<SidebarMenuButton asChild><Link href=...>`).
+   * 다른 엘리먼트(예: Next.js `Link`)로 대체. 자체로 `<button>` 을 렌더하므로
+   * 자식으로 또 다른 button/anchor 를 넣지 말 것. sh-ui 의 모든 슬롯 패턴은
+   * `render` 로 통일 (Base UI 표준).
    *
-   * @default false
+   *   <SidebarMenuButton render={<Link href='/'>홈</Link>} />
    */
-  asChild?: boolean;
+  render?: React.ReactElement;
   /**
    * `SidebarTOC` 안에서 활성 섹션 id를 자동 동기화. 이 값과 TOC active id가 일치하면
    * `isActive`가 자동으로 `true`가 된다.
@@ -610,12 +611,14 @@ export interface SidebarMenuButtonProps extends React.ButtonHTMLAttributes<HTMLB
 }
 
 /**
- * 메뉴 한 줄을 누를 수 있는 버튼. `asChild`로 `<a>` 등 다른 요소에 스타일만 입힐 수 있고,
- * `sectionId`(SidebarTOC 활성 동기화) / `panelId`(SidebarPanel 토글)를 지정해 활성 상태를 자동 결정한다.
+ * 메뉴 한 줄을 누를 수 있는 버튼. `render` prop 으로 `<a>` 등 다른 엘리먼트로
+ * 슬롯 가능 (Next.js Link 결합). `sectionId`/`panelId` 로 활성 상태 자동 결정.
+ *
+ *   <SidebarMenuButton render={<Link href='/projects'>All projects</Link>} />
  */
 export const SidebarMenuButton = React.forwardRef<HTMLButtonElement, SidebarMenuButtonProps>(
   function SidebarMenuButton(
-    { className, isActive, size = "md", asChild, sectionId, panelId, onClick, children, ...props },
+    { className, isActive, size = "md", render, sectionId, panelId, onClick, children, ...props },
     ref
   ) {
     const tocActive = useTOCActiveId();
@@ -640,15 +643,22 @@ export const SidebarMenuButton = React.forwardRef<HTMLButtonElement, SidebarMenu
       `sh-ui-sidebar__menu-button--${size}`,
       className);
 
-    if (asChild && React.isValidElement(children)) {
-      const child = children as React.ReactElement<Record<string, unknown>>;
-      const merged: Record<string, unknown> = {
-        ...props,
-        onClick: handleClick,
-        className: cn((child.props.className as string) || "", cls),
-        "data-active": resolvedIsActive || undefined,
-      };
-      return React.cloneElement(child, merged);
+    if (render && React.isValidElement(render)) {
+      const child = render as React.ReactElement<{
+        className?: string;
+        children?: React.ReactNode;
+      }>;
+      return React.cloneElement(
+        child,
+        {
+          ref,
+          ...props,
+          onClick: handleClick,
+          className: cn(child.props.className, cls),
+          "data-active": resolvedIsActive || undefined,
+        } as Record<string, unknown>,
+        children ?? child.props.children,
+      );
     }
 
     return (
@@ -697,18 +707,20 @@ export interface SidebarMenuSubButtonProps extends React.AnchorHTMLAttributes<HT
    */
   size?: "sm" | "md";
   /**
-   * Radix asChild 패턴. children에 다른 anchor 컴포넌트(예: Next.js Link)를 넘길 때 사용.
-   * @default false
+   * 다른 anchor 컴포넌트(예: Next.js `Link`)로 대체. sh-ui 의 모든 슬롯
+   * 패턴은 `render` 로 통일 (Base UI 표준).
+   *
+   *   <SidebarMenuSubButton render={<Link href='/...'>서브</Link>} />
    */
-  asChild?: boolean;
+  render?: React.ReactElement;
   /** `SidebarTOC`의 활성 섹션 id 자동 동기화. 일치하면 `isActive`가 자동으로 `true`. */
   sectionId?: string;
 }
 
-/** 서브 메뉴 항목 내부의 링크(`<a>`). `sectionId`로 SidebarTOC 활성 상태와 연동. */
+/** 서브 메뉴 항목 내부의 링크. `render` prop 으로 다른 엘리먼트 슬롯 가능. `sectionId`로 TOC 활성 연동. */
 export const SidebarMenuSubButton = React.forwardRef<HTMLAnchorElement, SidebarMenuSubButtonProps>(
   function SidebarMenuSubButton(
-    { className, isActive, size = "md", asChild, sectionId, children, ...props },
+    { className, isActive, size = "md", render, sectionId, children, ...props },
     ref
   ) {
     const tocActive = useTOCActiveId();
@@ -718,14 +730,21 @@ export const SidebarMenuSubButton = React.forwardRef<HTMLAnchorElement, SidebarM
       `sh-ui-sidebar__menu-sub-button--${size}`,
       className);
 
-    if (asChild && React.isValidElement(children)) {
-      const child = children as React.ReactElement<Record<string, unknown>>;
-      const merged: Record<string, unknown> = {
-        ...props,
-        className: cn((child.props.className as string) || "", cls),
-        "data-active": resolvedIsActive || undefined,
-      };
-      return React.cloneElement(child, merged);
+    if (render && React.isValidElement(render)) {
+      const child = render as React.ReactElement<{
+        className?: string;
+        children?: React.ReactNode;
+      }>;
+      return React.cloneElement(
+        child,
+        {
+          ref,
+          ...props,
+          className: cn(child.props.className, cls),
+          "data-active": resolvedIsActive || undefined,
+        } as Record<string, unknown>,
+        children ?? child.props.children,
+      );
     }
 
     return (
@@ -935,9 +954,7 @@ export function SidebarCollapsibleContent({ children }: { children: React.ReactN
  *   <SidebarTOC sectionIds={["intro", "install", "usage"]}>
  *     <SidebarMenu>
  *       <SidebarMenuItem>
- *         <SidebarMenuButton sectionId="intro" asChild>
- *           <a href="#intro">Intro</a>
- *         </SidebarMenuButton>
+ *         <SidebarMenuButton sectionId="intro" render={<a href="#intro">Intro</a>} />
  *       </SidebarMenuItem>
  *       ...
  *     </SidebarMenu>

package/data/summaries/react.json

@@ -27,9 +27,9 @@
     "tabs": "탭 — separate exports: Tabs / TabsList / TabsTrigger / TabsContent / TabsIndicator (Base UI). dot syntax(`Tabs.List`) 아님.",
     "accordion": "펼침/접힘 아코디언 — separate exports: Accordion / AccordionItem / AccordionTrigger / AccordionContent (Base UI). single/multiple 모드. AccordionTrigger 는 자체로 `<button>` — 다른 엘리먼트로 슬롯하려면 `render` prop 사용.",
     "carousel": "슬라이드 캐러셀 — Embla 기반, autoplay/autoscroll.",
-    "sidebar": "앱 사이드바 — collapsible, SidebarMenu/SidebarGroup 조합.",
+    "sidebar": "앱 사이드바 — SidebarProvider / Sidebar / SidebarInset / SidebarTrigger / SidebarHeader/Content/Footer / SidebarGroup·GroupLabel·GroupContent / SidebarMenu·MenuItem·MenuButton / SidebarMenuSub·SubItem·SubButton / SidebarCollapsible 등. SidebarMenuButton·SidebarMenuSubButton 은 자체 button/anchor — Next Link 등 다른 엘리먼트로 슬롯하려면 `render` prop 사용 (`<SidebarMenuButton render={<Link href='/'>홈</Link>} />`). asChild 는 v0.75 에서 제거됨.",
     "header": "앱 헤더 — 로고/네비/액션 compound, 데스크탑 inline / 모바일 drawer 자동 전환. drawer focus trap·ESC·focus restore. HeaderNav value(controlled) / defaultValue+onValueChange(uncontrolled) 로 자식 HeaderItem active 자동 매칭 (aria-current 자동, match 커스터마이즈). HeaderMenu(서브메뉴, 데스크탑 portal dropdown / drawer collapsible) · HeaderNavGroup(섹션 라벨) · HeaderDesktopOnly/HeaderMobileOnly(가시성 토글, drawer 이동 없음). variant(solid/transparent/blur) · stickyHide(prefers-reduced-motion 존중, 컨테이너 스크롤 자동 감지) 정식 지원. backdrop-filter @supports 폴백.",
-    "breadcrumb": "경로 내비게이션 — separate exports: Breadcrumb / BreadcrumbList / BreadcrumbItem / BreadcrumbLink / BreadcrumbPage / BreadcrumbSeparator / BreadcrumbEllipsis. dot syntax 아님. aria-current 자동.",
+    "breadcrumb": "경로 내비게이션 — separate exports: Breadcrumb / BreadcrumbList / BreadcrumbItem / BreadcrumbLink / BreadcrumbPage / BreadcrumbSeparator / BreadcrumbEllipsis. BreadcrumbLink 는 자체 `<a>` — Next Link 등 다른 엘리먼트로 슬롯하려면 `render` prop 사용 (`<BreadcrumbLink render={<Link href='/...'>Projects</Link>} />`). aria-current 자동.",
     "pagination": "페이지 단위 내비게이션 — separate exports: Pagination / PaginationContent / PaginationItem / PaginationLink / PaginationPrevious / PaginationNext / PaginationEllipsis. getPaginationRange 유틸 동봉. aria-current 자동.",
     "avatar": "프로필 아바타 — 이미지 fallback → initials (Base UI).",
     "badge": "상태 뱃지 — variant, size.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh-ui-cli",
-  "version": "0.74.1",
+  "version": "0.76.0",
   "description": "sh-ui CLI — 프로젝트 스캐폴드(create) + 컴포넌트 추가(add/list/remove) + IDE-내 AI용 MCP 서버",
   "license": "MIT",
   "repository": {
@@ -27,10 +27,10 @@
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "zod": "^4.3.6"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "fs-extra": "^11.2.0",
+    "fs-extra": "^11.3.5",
     "vitest": "^3.2.4"
   },
   "publishConfig": {

package/src/mcp-init.mjs

@@ -4,20 +4,25 @@
 //   claude-code     — project: <cwd>/.mcp.json,           user: ~/.claude.json
 //   cursor          — project: <cwd>/.cursor/mcp.json,    user: ~/.cursor/mcp.json
 //   claude-desktop  — user 만 (OS 별 경로 자동 분기)
+//   codex           — user 만 (~/.codex/config.toml — TOML 포맷)
 //
 // 주의: Claude Code 의 user-scope 설정은 `~/.claude/mcp.json` 같은 별도
 // 파일이 아니라 사용자 settings 전체가 들어가는 단일 JSON `~/.claude.json`
 // 이다. 이 파일에는 mcpServers 외에도 projects·history 등 다른 키가 같이
-// 들어 있으므로, 머지 시 다른 키를 절대 건드리지 않아야 한다.
+// 들어 있으므로, 머지 시 다른 키를 절대 건드리지 않아야 한다. codex 의
+// config.toml 도 같은 원칙 — 다른 섹션은 건드리지 않고 `[mcp_servers.sh-ui]`
+// 만 upsert 한다.
 //
-// 동작: 기존 JSON 의 mcpServers.sh-ui 를 머지(있으면 덮어쓰기), 디렉토리 자동 생성.
+// 동작: JSON 클라이언트는 mcpServers.sh-ui 머지(있으면 덮어쓰기). codex 는
+// `[mcp_servers.sh-ui]` 섹션 텍스트를 통째로 교체(존재하지 않으면 append).
+// 디렉토리는 자동 생성.
 
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { dirname, resolve, relative } from "node:path";
 import { homedir, platform as osPlatform } from "node:os";
 
-const CLIENTS = ["claude-code", "cursor", "claude-desktop"];
+const CLIENTS = ["claude-code", "cursor", "claude-desktop", "codex"];
 
 /**
  * `npx -y <cliName> mcp` 형태의 MCP 엔트리 빌더.
@@ -68,12 +73,138 @@ function resolveConfigPath(client, scope, cwd) {
     // linux + 기타
     return resolve(home, ".config", "Claude", "claude_desktop_config.json");
   }
+  if (client === "codex") {
+    if (scope !== "user") {
+      throw new Error(
+        "codex 는 user 스코프만 지원합니다. --scope user 또는 --scope 생략.",
+      );
+    }
+    return resolve(home, ".codex", "config.toml");
+  }
   throw new Error(`알 수 없는 클라이언트: ${client}. 허용: ${CLIENTS.join(", ")}`);
 }
 
-/** 클라이언트별 기본 스코프. claude-desktop 은 user 강제. */
+/** 클라이언트별 기본 스코프. claude-desktop·codex 는 user 강제. */
 function defaultScope(client) {
-  return client === "claude-desktop" ? "user" : "project";
+  return client === "claude-desktop" || client === "codex" ? "user" : "project";
+}
+
+/**
+ * codex `~/.codex/config.toml` 의 `[mcp_servers.<name>]` 섹션 upsert.
+ *
+ * 텍스트 기반 — 다른 섹션·주석·공백을 보존하기 위해 TOML 파서를 안 쓴다.
+ * `[mcp_servers.<name>]` 와 그 하위 (`[mcp_servers.<name>.env]` 등) 모두
+ * 제거 후, 새 블록을 파일 끝에 append.
+ *
+ * 한계: 사용자가 inline-table 형태(`[mcp_servers]` 부모 섹션 안에
+ * `sh-ui = { command = ... }`)로 정의해두면 그건 감지·정리하지 못한다.
+ * 그 경우 새 섹션과 충돌하므로 detect → 명시적 에러.
+ */
+export function upsertCodexMcpServer(raw, name, entry) {
+  detectInlineMcpServer(raw, name);
+  const had = hasCodexMcpServerSection(raw, name);
+
+  const lines = raw.split("\n");
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    if (isOurSectionHeader(lines[i], name)) {
+      // 섹션 본문 끝(다음 헤더 직전 또는 EOF)까지 skip
+      i++;
+      while (i < lines.length && !isAnySectionHeader(lines[i])) i++;
+      // 새 블록을 끝에 붙일 거라, 우리가 지운 섹션 직전의 빈 줄은 정리
+      while (out.length && out[out.length - 1].trim() === "") out.pop();
+    } else {
+      out.push(lines[i]);
+      i++;
+    }
+  }
+
+  let head = out.join("\n").replace(/\s+$/, "");
+  const block = renderCodexBlock(name, entry);
+  const next = head === "" ? block + "\n" : head + "\n\n" + block + "\n";
+  return { text: next, had };
+}
+
+function isAnySectionHeader(line) {
+  return /^\s*\[[^\]]+\]\s*$/.test(line);
+}
+
+function isOurSectionHeader(line, name) {
+  const m = line.match(/^\s*\[([^\]]+)\]\s*$/);
+  if (!m) return false;
+  const path = m[1].trim();
+  const bare = `mcp_servers.${name}`;
+  const quoted = `mcp_servers."${name}"`;
+  return (
+    path === bare ||
+    path === quoted ||
+    path.startsWith(bare + ".") ||
+    path.startsWith(quoted + ".")
+  );
+}
+
+function hasCodexMcpServerSection(raw, name) {
+  return raw.split("\n").some((line) => {
+    const m = line.match(/^\s*\[([^\]]+)\]\s*$/);
+    if (!m) return false;
+    const path = m[1].trim();
+    return path === `mcp_servers.${name}` || path === `mcp_servers."${name}"`;
+  });
+}
+
+/** `[mcp_servers]` 부모 섹션 안에 `<name> =` 로 inline 정의돼 있으면 에러. */
+function detectInlineMcpServer(raw, name) {
+  const lines = raw.split("\n");
+  let inMcpServers = false;
+  for (const line of lines) {
+    const headerMatch = line.match(/^\s*\[([^\]]+)\]\s*$/);
+    if (headerMatch) {
+      inMcpServers = headerMatch[1].trim() === "mcp_servers";
+      continue;
+    }
+    if (!inMcpServers) continue;
+    const keyRegex = new RegExp(`^\\s*(?:${escapeReg(name)}|"${escapeReg(name)}")\\s*=`);
+    if (keyRegex.test(line)) {
+      throw new Error(
+        `기존 config.toml 의 [mcp_servers] 섹션 안에 '${name}' 가 inline-table 로 정의돼 있습니다.\n` +
+          `자동 갱신을 지원하지 않으니, 해당 줄을 직접 제거한 뒤 다시 실행하세요.`,
+      );
+    }
+  }
+}
+
+function escapeReg(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function renderCodexBlock(name, entry) {
+  const header = `[mcp_servers.${tomlBareOrQuoted(name)}]`;
+  const lines = [header];
+  lines.push(`command = ${tomlBasicString(entry.command)}`);
+  lines.push(`args = ${tomlInlineArray(entry.args)}`);
+  if (entry.env && Object.keys(entry.env).length > 0) {
+    lines.push("");
+    lines.push(`[mcp_servers.${tomlBareOrQuoted(name)}.env]`);
+    for (const [k, v] of Object.entries(entry.env)) {
+      lines.push(`${tomlBareOrQuoted(k)} = ${tomlBasicString(v)}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function tomlBareOrQuoted(key) {
+  return /^[A-Za-z0-9_-]+$/.test(key) ? key : tomlBasicString(key);
+}
+
+function tomlBasicString(s) {
+  // TOML basic string 은 JSON string 과 escape 규칙이 호환 (\" \\ \n \t \r \b \f \uXXXX).
+  // ASCII 위주 값(npx, sh-ui-cli, mcp 등)에 한해 안전.
+  return JSON.stringify(String(s));
+}
+
+function tomlInlineArray(arr) {
+  return `[${arr.map(tomlBasicString).join(", ")}]`;
 }
 
 /** JSON 읽기 (없으면 빈 객체). 깨진 JSON 은 명시적 에러. */
@@ -116,28 +247,38 @@ export async function mcpInit({ cwd, args }) {
   }
 
   const configPath = resolveConfigPath(client, scope, cwd);
-  const config = await readJsonOrEmpty(configPath);
+  const entry = await buildShUiEntry();
 
-  if (!config.mcpServers || typeof config.mcpServers !== "object") {
-    config.mcpServers = {};
+  let had;
+  if (client === "codex") {
+    const raw = existsSync(configPath) ? await readFile(configPath, "utf8") : "";
+    const { text, had: existed } = upsertCodexMcpServer(raw, "sh-ui", entry);
+    had = existed;
+    await mkdir(dirname(configPath), { recursive: true });
+    await writeFile(configPath, text, "utf8");
+  } else {
+    const config = await readJsonOrEmpty(configPath);
+    if (!config.mcpServers || typeof config.mcpServers !== "object") {
+      config.mcpServers = {};
+    }
+    had = Boolean(config.mcpServers["sh-ui"]);
+    config.mcpServers["sh-ui"] = entry;
+    await mkdir(dirname(configPath), { recursive: true });
+    await writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
   }
 
-  const before = config.mcpServers["sh-ui"];
-  config.mcpServers["sh-ui"] = await buildShUiEntry();
-
-  await mkdir(dirname(configPath), { recursive: true });
-  await writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
-
   const rel = relative(cwd, configPath);
   const display = rel.startsWith("..") ? configPath : rel;
-  const verb = before ? "갱신" : "추가";
+  const verb = had ? "갱신" : "추가";
   console.log(`✓ sh-ui MCP 엔트리 ${verb} → ${display}`);
   console.log(`  client: ${client} (scope: ${scope})`);
-  if (client === "claude-code" || client === "cursor") {
-    console.log(`\n다음 단계: ${client === "claude-code" ? "Claude Code" : "Cursor"} 를 재시작하면 sh-ui 툴이 활성화됩니다.`);
-  } else {
-    console.log(`\n다음 단계: Claude Desktop 을 종료 후 재시작하면 sh-ui 툴이 활성화됩니다.`);
-  }
+  const restartTarget = {
+    "claude-code": "Claude Code",
+    cursor: "Cursor",
+    "claude-desktop": "Claude Desktop",
+    codex: "codex CLI 세션",
+  }[client];
+  console.log(`\n다음 단계: ${restartTarget} 를 재시작하면 sh-ui 툴이 활성화됩니다.`);
 }
 
 /** --key=value / --key value 파싱 */