sh-ui-cli 0.22.1 → 0.23.0

package/src/create/theme/decode.js

@@ -0,0 +1,66 @@
+const TOKEN_KEYS = [
+  'background', 'background-subtle', 'background-muted',
+  'foreground', 'foreground-muted',
+  'border', 'border-strong',
+  'primary', 'primary-foreground', 'primary-hover',
+  'danger', 'danger-foreground',
+];
+
+const HEX_REGEX = /^#[0-9A-Fa-f]{6}$/;
+const BASE64_REGEX = /^[A-Za-z0-9+/]*={0,2}$/;
+const MAX_THEME_BYTES = 10 * 1024; // 정상 테마 ~860 바이트. 10KB 면 10× 여유.
+
+const validateTokenMap = (name, map) => {
+  if (!map || typeof map !== 'object') {
+    throw new Error(`theme 디코드 실패: ${name} 가 객체가 아님`);
+  }
+  for (const key of TOKEN_KEYS) {
+    if (!(key in map)) {
+      throw new Error(`theme 디코드 실패: ${name}.${key} 누락`);
+    }
+    const value = map[key];
+    if (typeof value !== 'string' || !HEX_REGEX.test(value)) {
+      throw new Error(
+        `theme 디코드 실패: ${name}.${key} 가 hex 포맷이 아님 (받은 값: ${JSON.stringify(value)})`,
+      );
+    }
+  }
+};
+
+export const decodeTheme = (b64) => {
+  if (typeof b64 !== 'string') {
+    throw new Error(`theme 디코드 실패: 문자열이 아님`);
+  }
+  if (b64.length > MAX_THEME_BYTES) {
+    throw new Error(
+      `theme 크기가 허용 범위를 초과함 (${b64.length} > ${MAX_THEME_BYTES} 바이트). ` +
+      `playground 에서 생성한 값만 사용하세요.`
+    );
+  }
+  if (!BASE64_REGEX.test(b64)) {
+    throw new Error(`theme 디코드 실패: base64 포맷이 아님`);
+  }
+  let json;
+  try {
+    json = Buffer.from(b64, 'base64').toString('utf-8');
+  } catch (e) {
+    throw new Error(`theme 디코드 실패: base64 디코드 실패 (${e.message})`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch (e) {
+    throw new Error(`theme 디코드 실패: JSON 파싱 실패 (${e.message})`);
+  }
+  validateTokenMap('light', parsed.light);
+  validateTokenMap('dark', parsed.dark);
+  if (typeof parsed.radius !== 'number' || Number.isNaN(parsed.radius)) {
+    throw new Error(`theme 디코드 실패: radius 가 숫자가 아님`);
+  }
+  if (parsed.radius < 0 || parsed.radius > 1.5) {
+    throw new Error(`theme 디코드 실패: radius 가 허용 범위(0~1.5)를 벗어남 (${parsed.radius})`);
+  }
+  return parsed;
+};
+
+export { TOKEN_KEYS };

package/src/create/theme/inject.js

@@ -0,0 +1,111 @@
+import { TOKEN_KEYS } from './decode.js';
+
+/**
+ * 파일 내용에서 sh-ui:<section>-start / -end 마커 사이 내용을 교체.
+ * commentOpen / commentClose 는 파일 형식에 따라 주어짐:
+ *   CSS  → '/*', '*' + '/'
+ *   Dart → '//', ''
+ */
+export const replaceSection = (content, section, commentOpen, commentClose, replacement) => {
+  const startMarker = commentClose
+    ? `${commentOpen} sh-ui:${section}-start ${commentClose}`
+    : `${commentOpen} sh-ui:${section}-start`;
+  const endMarker = commentClose
+    ? `${commentOpen} sh-ui:${section}-end ${commentClose}`
+    : `${commentOpen} sh-ui:${section}-end`;
+
+  const startIdx = content.indexOf(startMarker);
+  const endIdx = content.indexOf(endMarker);
+  if (startIdx < 0 || endIdx < 0 || endIdx < startIdx) {
+    throw new Error(`inject 실패: 섹션 ${section} 마커 없음`);
+  }
+
+  const before = content.slice(0, startIdx + startMarker.length);
+  const after = content.slice(endIdx);
+  return `${before}\n${replacement}\n${after}`;
+};
+
+// ─── CSS 블록 빌더 ───
+
+const cssColorLine = (key, value) => `  --${key}: ${value};`;
+
+export const buildCssColorsBlock = (theme) => {
+  const lightLines = TOKEN_KEYS.map((k) => cssColorLine(k, theme.light[k])).join('\n');
+  const darkLines = TOKEN_KEYS.map((k) => cssColorLine(k, theme.dark[k])).join('\n');
+  return [
+    ':root {',
+    lightLines,
+    '}',
+    '.dark {',
+    darkLines,
+    '}',
+  ].join('\n');
+};
+
+export const buildCssRadiusBlock = (theme) => {
+  return `  --radius: ${theme.radius}rem;`;
+};
+
+// ─── Dart 블록 빌더 ───
+
+const toDartColor = (hex) => `Color(0xFF${hex.replace('#', '').toUpperCase()})`;
+
+/**
+ * Dart 의 ShUiColorTokens 필드 순서 + 각 필드가 어떤 소스에서 값을 가져오는지.
+ *   self    — 현재 모드의 편집값
+ *   inverse — 반대 모드의 편집값
+ *   default — playground 가 노출하지 않음, 고정 기본값 사용
+ */
+const DART_FIELD_SOURCES = [
+  { field: 'background',           source: { kind: 'self', key: 'background' } },
+  { field: 'backgroundSubtle',     source: { kind: 'self', key: 'background-subtle' } },
+  { field: 'backgroundMuted',      source: { kind: 'self', key: 'background-muted' } },
+  { field: 'backgroundInverse',    source: { kind: 'inverse', key: 'background' } },
+  { field: 'foreground',           source: { kind: 'self', key: 'foreground' } },
+  { field: 'foregroundMuted',      source: { kind: 'self', key: 'foreground-muted' } },
+  { field: 'foregroundSubtle',     source: { kind: 'default' } },
+  { field: 'foregroundInverse',    source: { kind: 'inverse', key: 'foreground' } },
+  { field: 'border',               source: { kind: 'self', key: 'border' } },
+  { field: 'borderStrong',         source: { kind: 'self', key: 'border-strong' } },
+  { field: 'primary',              source: { kind: 'self', key: 'primary' } },
+  { field: 'primaryForeground',    source: { kind: 'self', key: 'primary-foreground' } },
+  { field: 'primaryHover',         source: { kind: 'self', key: 'primary-hover' } },
+  { field: 'danger',               source: { kind: 'self', key: 'danger' } },
+  { field: 'dangerForeground',     source: { kind: 'self', key: 'danger-foreground' } },
+];
+
+const DART_DEFAULTS = {
+  light: { foregroundSubtle: '0xFFA3A3A3' },
+  dark:  { foregroundSubtle: '0xFF737373' },
+};
+
+const buildDartStaticConst = (mode, self, opposite) => {
+  const lines = DART_FIELD_SOURCES.map(({ field, source }) => {
+    switch (source.kind) {
+      case 'self':
+        return `    ${field}: ${toDartColor(self[source.key])},`;
+      case 'inverse':
+        return `    ${field}: ${toDartColor(opposite[source.key])},`;
+      case 'default':
+        return `    ${field}: Color(${DART_DEFAULTS[mode][field]}),`;
+    }
+  }).join('\n');
+  return [
+    `  static const ${mode} = ShUiColorTokens(`,
+    lines,
+    '  );',
+  ].join('\n');
+};
+
+export const buildDartColorsBlock = (theme) => {
+  return [
+    buildDartStaticConst('light', theme.light, theme.dark),
+    '',
+    buildDartStaticConst('dark', theme.dark, theme.light),
+  ].join('\n');
+};
+
+export const buildDartRadiusBlock = (theme) => {
+  const px = (theme.radius * 16).toFixed(1);
+  return `    defaultRadius: ${px},`;
+};

package/src/mcp.mjs

@@ -13,6 +13,7 @@
 //   sh_ui_remove_component - 컴포넌트 삭제
 
 import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -22,6 +23,7 @@ import { init } from "./init.mjs";
 import { add } from "./add.mjs";
 import { list } from "./list.mjs";
 import { remove } from "./remove.mjs";
+import { createProject } from "./create/generator.js";
 import {
   getRegistryRoot,
   getSummariesPath,
@@ -100,10 +102,44 @@ function resolveCwd(input) {
   return input?.cwd ? resolve(input.cwd) : process.cwd();
 }
 
+const SERVER_INSTRUCTIONS = `sh-ui — Base UI 위에 빌드된 React/Flutter 디자인 시스템.
+
+## 새 프로젝트를 만드는 경우
+
+빈 폴더에서 시작하거나 사용자가 "Next.js 앱 만들어줘", "Flutter 프로젝트 새로", "sh-ui 로 시작" 처럼 **스캐폴드부터** 요청하면:
+
+**1차 — \`sh_ui_create_project\` MCP 툴** (선호):
+  - 인자: name, platform (next|flutter), structure (next 일 때 standalone|monorepo), plugins (선택), force (덮어쓰기)
+  - 인터랙티브 프롬프트 없이 한 번에 스캐폴드 + 토큰 + sh-ui.config.json 생성
+
+**2차 — Bash** (사용자가 직접 셸에서 돌리고 싶다고 명시할 때만):
+  npm create sh-ui my-app
+  npx sh-ui-cli create my-app --platform next --structure standalone --yes
+
+\`create-next-app\` + \`sh_ui_init\` 조합은 **쓰지 말 것** — 위 두 경로가 더 짧고 sh-ui 관용에 맞다.
+
+## 이미 있는 프로젝트에 sh-ui 를 얹는 경우 (MCP 툴 사용)
+
+기존 Next.js/Vite/Flutter 프로젝트에 sh-ui 컴포넌트만 추가하고 싶을 때:
+1. \`sh_ui_describe_init\` — 자연어 의도("다크 모던")를 enum 으로 매핑
+2. \`sh_ui_init\` — \`sh-ui.config.json\` 생성
+3. \`sh_ui_add_component\` — \`tokens\` 먼저, 그다음 컴포넌트
+
+## 컴포넌트 작업
+
+- \`sh_ui_list_components\` — 어떤 게 있는지
+- \`sh_ui_get_component\` — props/소스 확인 (코드 작성 전)
+- \`sh_ui_add_component\` / \`sh_ui_remove_component\` — 설치/삭제
+- \`sh_ui_get_changelog\` — 최근 변경 내역
+`;
+
 export async function startMcpServer() {
   const server = new McpServer(
-    { name: "sh-ui", version: "0.22.1" },
-    { capabilities: { tools: {} } },
+    { name: "sh-ui", version: "0.23.0" }, // sh-ui-cli 와 동기화
+    {
+      capabilities: { tools: {} },
+      instructions: SERVER_INSTRUCTIONS,
+    },
   );
 
   server.registerTool(
@@ -117,10 +153,80 @@ export async function startMcpServer() {
     async () => jsonResult(INIT_DESCRIPTIONS),
   );
 
+  server.registerTool(
+    "sh_ui_create_project",
+    {
+      description:
+        "빈 폴더에 sh-ui 프로젝트 스캐폴드 — Next.js (standalone/monorepo) 또는 Flutter. " +
+        "FSD 폴더 구조 + 토큰 + sh-ui.config.json 일괄 생성. 사용자가 '새 프로젝트' / '빈 폴더' / '스캐폴드부터' 류 요청을 하면 이 툴 사용 (Bash 로 npx sh-ui-cli create 직접 호출보다 우선).",
+      inputSchema: {
+        name: z.string().min(1)
+          .describe("프로젝트 디렉토리 이름. 예: my-app"),
+        platform: z.enum(["next", "flutter"])
+          .describe("타겟 플랫폼"),
+        structure: z.enum(["standalone", "monorepo"]).optional()
+          .describe("Next.js 구조 — platform=next 일 때 필수. standalone(단독) | monorepo(Turborepo)"),
+        plugins: z.array(z.enum(["sentry", "next-intl"])).optional()
+          .describe("Next.js 플러그인. 미지정시 빈 배열"),
+        theme: z.string().optional()
+          .describe("base64 인코딩된 테마 JSON (선택)"),
+        cwd: z.string().optional()
+          .describe("부모 디렉토리. 기본 process.cwd()"),
+        force: z.boolean().optional()
+          .describe("기존 디렉토리 덮어쓰기. 기본 false (안전)"),
+      },
+    },
+    async (input) => {
+      if (input.platform === "next" && !input.structure) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: "platform=next 일 때 structure ('standalone' | 'monorepo') 가 필요합니다.",
+            },
+          ],
+        };
+      }
+      const targetParent = resolveCwd(input);
+      const targetDir = resolve(targetParent, input.name);
+      if (existsSync(targetDir) && !input.force) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `'${targetDir}' 가 이미 존재합니다. 덮어쓰려면 force: true.`,
+            },
+          ],
+        };
+      }
+      const origCwd = process.cwd();
+      try {
+        process.chdir(targetParent);
+        const text = await captureConsole(() =>
+          createProject({
+            name: input.name,
+            platform: input.platform,
+            structure: input.structure,
+            plugins: input.plugins,
+            theme: input.theme,
+            yes: true, // 사전 검사를 마쳤으니 generator 의 confirm 프롬프트 우회
+          }),
+        );
+        return textResult(text || "✓ 프로젝트 생성 완료");
+      } finally {
+        process.chdir(origCwd);
+      }
+    },
+  );
+
   server.registerTool(
     "sh_ui_init",
     {
       description:
+        "⚠️ 빈 폴더/새 프로젝트면 이 툴 대신 sh_ui_create_project 사용 — 스캐폴드 + 토큰 + config 일괄 처리. " +
+        "이 툴은 **이미 있는** Next.js/Vite/Flutter 프로젝트에 sh-ui 만 얹을 때. " +
         "현재 디렉토리(또는 cwd)에 sh-ui.config.json 을 생성. 비대화형 — 누락된 값은 기본값 사용. " +
         "선택지 의미가 헷갈리면 먼저 sh_ui_describe_init 호출 권장.",
       inputSchema: {

package/src/paths.mjs

@@ -47,6 +47,11 @@ export function getSummariesPath(platform) {
     : resolve(MONOREPO_PACKAGES, "llms", "summaries", `${platform}.json`);
 }
 
+/** sh-ui create 용 프로젝트 템플릿 루트 — 이 패키지 안에 직접 들어있다 */
+export function getTemplatesRoot() {
+  return resolve(CLI_ROOT, "templates");
+}
+
 /** 변경 내역 JSON */
 export function getVersionsPath() {
   return isBundled

package/templates/flutter-standalone/README.md

@@ -0,0 +1,34 @@
+# {{project_name}}
+
+sh-ui 기반 Flutter 앱.
+
+## 시작하기
+
+```bash
+flutter pub get
+flutter run
+```
+
+## sh-ui 위젯 추가
+
+```bash
+npx sh-ui add button
+npx sh-ui add card input
+```
+
+위젯은 `lib/sh_ui/widgets/` 아래로 복사됩니다. 설정은 `sh-ui.config.json` 을 참조하세요.
+
+## 구조
+
+```
+lib/
+├── main.dart                        # 앱 진입점
+└── sh_ui/                           # sh-ui 자산 (건드리지 말 것 — sh-ui CLI 가 관리)
+    ├── foundation/
+    │   └── sh_ui_tokens.dart        # 디자인 토큰
+    └── widgets/                     # sh-ui add 로 추가되는 위젯들
+```
+
+## 더 알아보기
+
+- sh-ui 컴포넌트 목록 및 가이드: https://github.com/sanghyeonKim0201/sh-ui

package/templates/flutter-standalone/analysis_options.yaml

@@ -0,0 +1 @@
+include: package:flutter_lints/flutter.yaml

package/templates/flutter-standalone/lib/main.dart

@@ -0,0 +1,103 @@
+import 'package:flutter/material.dart';
+import 'sh_ui/foundation/sh_ui_tokens.dart';
+
+void main() {
+  runApp(const MyApp());
+}
+
+class MyApp extends StatefulWidget {
+  const MyApp({super.key});
+
+  @override
+  State<MyApp> createState() => _MyAppState();
+}
+
+class _MyAppState extends State<MyApp> {
+  ThemeMode _themeMode = ThemeMode.light;
+
+  void _toggleTheme() {
+    setState(() {
+      _themeMode =
+          _themeMode == ThemeMode.light ? ThemeMode.dark : ThemeMode.light;
+    });
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      title: '{{project_name}}',
+      debugShowCheckedModeBanner: false,
+      themeMode: _themeMode,
+      theme: ThemeData(
+        brightness: Brightness.light,
+        scaffoldBackgroundColor: ShUiColorTokens.light.background,
+        extensions: const [ShUiTheme.light],
+      ),
+      darkTheme: ThemeData(
+        brightness: Brightness.dark,
+        scaffoldBackgroundColor: ShUiColorTokens.dark.background,
+        extensions: const [ShUiTheme.dark],
+      ),
+      home: HomePage(
+        themeMode: _themeMode,
+        onToggleTheme: _toggleTheme,
+      ),
+    );
+  }
+}
+
+class HomePage extends StatelessWidget {
+  const HomePage({
+    super.key,
+    required this.themeMode,
+    required this.onToggleTheme,
+  });
+
+  final ThemeMode themeMode;
+  final VoidCallback onToggleTheme;
+
+  @override
+  Widget build(BuildContext context) {
+    final shUi = Theme.of(context).extension<ShUiTheme>() ?? ShUiTheme.light;
+    final colors = shUi.colors;
+
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('{{project_name}}'),
+        actions: [
+          IconButton(
+            icon: Icon(
+              themeMode == ThemeMode.light
+                  ? Icons.dark_mode_outlined
+                  : Icons.light_mode_outlined,
+            ),
+            onPressed: onToggleTheme,
+          ),
+        ],
+      ),
+      body: Center(
+        child: Column(
+          mainAxisAlignment: MainAxisAlignment.center,
+          children: [
+            Text(
+              'sh-ui 기반 Flutter 앱',
+              style: TextStyle(
+                color: colors.foreground,
+                fontSize: 20,
+                fontWeight: FontWeight.w600,
+              ),
+            ),
+            const SizedBox(height: 12),
+            Text(
+              'sh-ui add <widget> 로 위젯을 추가해 보세요',
+              style: TextStyle(
+                color: colors.foregroundMuted,
+                fontSize: 14,
+              ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}