sh-ui-cli 0.114.0 → 0.116.0

package/data/registry/react/tokens-used.json

@@ -1,6 +1,6 @@
 {
   "$description": "컴포넌트별 토큰 의존성 (var(--*) 추출). build-registry-tokens.mjs 가 자동 생성.",
-  "$generated": "2026-05-26T05:20:38.023Z",
+  "$generated": "2026-06-01T06:54:04.570Z",
   "components": {
     "button": {
       "plain": [
@@ -533,6 +533,7 @@
         "--primary",
         "--radius",
         "--ring",
+        "--sh-ui-rte-c-",
         "--space-1",
         "--space-2",
         "--space-3",
@@ -551,6 +552,7 @@
         "--opacity-disabled",
         "--primary",
         "--radius",
+        "--sh-ui-rte-c-",
         "--space-1",
         "--space-2",
         "--space-3",
@@ -571,6 +573,7 @@
         "--primary",
         "--radius",
         "--ring",
+        "--sh-ui-rte-c-",
         "--space-1",
         "--space-2",
         "--space-3",

package/package.json

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

package/src/add.mjs

@@ -5,6 +5,7 @@ import { pathToFileURL } from "node:url";
 import { spawn } from "node:child_process";
 import { select } from "@inquirer/prompts";
 import { formatUnifiedDiff } from "./diff.mjs";
+import { suggest } from "./levenshtein.mjs";
 import { getRegistryRoot, getTokensRoot, getPeerVersionsPath } from "./paths.mjs";
 import { THEME_BASES } from "./constants.js";
 import {
@@ -20,6 +21,25 @@ import {
   rewriteCrossComponentImports,
 } from "./css-bundle.mjs";
 
+export const HELP_TEXT = `sh-ui add — 컴포넌트 소스를 프로젝트로 복사 + 필요한 패키지 자동 설치
+
+사용법:
+  sh-ui add <component...>
+  sh-ui add tokens          설정 기반 토큰 파일 생성 (특수값)
+
+옵션:
+  --skip-install   외부 패키지 자동 설치 생략
+  --diff           파일을 쓰지 않고 변경 내역(unified diff)만 출력
+  --force          기존 파일을 모두 덮어쓰기 (prompt 없음)
+  --keep           기존 파일을 모두 유지 (prompt 없음)
+  --app <name>     monorepo 라우팅 시 대상 ui-{name} 명시
+
+예:
+  sh-ui add button
+  sh-ui add button card --diff
+  sh-ui add tokens
+`;
+
 /**
  * 기존 파일과 registry 파일 내용이 다를 때 keep/overwrite 결정.
  * strategy 가 "prompt" 면 사용자에게 묻고, 그 외엔 즉시 결정.
@@ -336,6 +356,16 @@ function effectiveFramework(entry, cssFramework) {
   return hasVariant ? cssFramework : "plain";
 }
 
+/** 컴포넌트 not-found 에러 메시지. 가까운 후보가 있으면 "혹시 …?" 를 덧붙인다. */
+export function buildNotFoundMessage(name, platform, candidates) {
+  const hits = suggest(name, candidates);
+  const hint = hits.length ? ` 혹시 ${hits.join(", ")}?` : "";
+  return (
+    `'${name}' 컴포넌트를 ${platform} 레지스트리에서 찾을 수 없습니다.${hint}` +
+    ` 전체 목록: sh-ui list --all`
+  );
+}
+
 async function addComponent(name, config, cwd, installed, pendingDeps, diffMode, summary, conflictResolver, validationCtx) {
   const registryRoot = getRegistryRoot(config.platform);
   const registry = JSON.parse(
@@ -344,7 +374,7 @@ async function addComponent(name, config, cwd, installed, pendingDeps, diffMode,
   const entry = registry.components?.[name];
   if (!entry) {
     throw new Error(
-      `'${name}' 컴포넌트를 ${config.platform} 레지스트리에서 찾을 수 없습니다.`,
+      buildNotFoundMessage(name, config.platform, Object.keys(registry.components ?? {})),
     );
   }
 

package/src/commands.mjs

@@ -0,0 +1,6 @@
+// CLI 최상위 명령 목록 — bin 라우터와 did-you-mean 추천이 공유.
+export const KNOWN_COMMANDS = [
+  "create", "init", "add", "list", "doctor", "upgrade-cli",
+  "theme", "tokens", "mcp", "rename-app", "migrate", "migrate-v065",
+  "remove", "rm",
+];

package/src/create/generator.js

@@ -678,6 +678,10 @@ async function inferMonorepoPlatform(cwd) {
  * @param {string} [options.onConflict]           'prompt' | 'keep' | 'overwrite'
  */
 export async function addComponent(options = {}) {
+  // monorepo 라우팅은 컴포넌트별 registry 조회를 직접 하지 않고 add() 로 위임한다.
+  // 따라서 not-found 처리(오타 추천 포함)는 add.mjs 의 addComponent 가 공유 헬퍼
+  // buildNotFoundMessage 로 던지는 메시지를 그대로 쓴다 — standalone 경로와 동일,
+  // 메시지 로직 중복 없음 (DRY).
   const { add } = await import('../add.mjs');
 
   const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();

package/src/doctor.mjs

@@ -18,6 +18,20 @@ import {
   findMissingTokens,
 } from "./tokens-validate.mjs";
 
+export const HELP_TEXT = `sh-ui doctor — 프로젝트 정합성 점검
+
+사용법:
+  sh-ui doctor
+
+점검 항목:
+  config    sh-ui.config.json 존재·필드 유효성
+  tokens    tokens.css 정의·필요 변수 누락 여부
+  설치된 컴포넌트   소스/스타일 파일 정합성
+
+예:
+  sh-ui doctor
+`;
+
 const ICON = { ok: "✓", warn: "⚠", fail: "✗" };
 
 class Report {

package/src/init.mjs

@@ -13,6 +13,25 @@ import {
   CSS_FRAMEWORKS_PLANNED,
 } from "./constants.js";
 
+export const HELP_TEXT = `sh-ui init — sh-ui.config.json 생성 (기존 프로젝트에 sh-ui 얹기)
+
+사용법:
+  sh-ui init [options]
+
+옵션:
+  --platform <react|flutter>   타겟 플랫폼
+  --base <neutral|zinc|...>    색 베이스
+  --radius <none|sm|md|lg|xl|full>  모서리 반경
+  --mode <light|dark|light-dark>    색 모드
+  --cssFramework <plain|tailwind|css-modules>  CSS 전략 (vanilla-extract 예정)
+  --force                      기존 sh-ui.config.json 덮어쓰기
+  --yes                        대화형 프롬프트 생략 (기본값 채택)
+
+예:
+  sh-ui init
+  sh-ui init --platform react --base neutral --mode light-dark --yes
+`;
+
 const CHOICES = {
   platform: INIT_PLATFORMS,
   base: THEME_BASES,

package/src/levenshtein.mjs

@@ -0,0 +1,36 @@
+// 의존성 없는 편집거리 + 후보 제안. diff.mjs 가 LCS 를 자체 구현한 관행을 따른다.
+
+/** 두 문자열의 Levenshtein 편집거리 (삽입/삭제/치환 비용 1). */
+export function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  let curr = new Array(n + 1);
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}
+
+/**
+ * input 과 가까운 candidates 를 거리 오름차순으로 반환.
+ * @param {string} input
+ * @param {string[]} candidates
+ * @param {{max?: number, maxDistance?: number}} [opts]
+ * @returns {string[]} 거리 <= maxDistance 인 후보 상위 max 개 (없으면 빈 배열)
+ */
+export function suggest(input, candidates, { max = 3, maxDistance = 2 } = {}) {
+  return candidates
+    .map((name) => ({ name, dist: levenshtein(input, name) }))
+    .filter((c) => c.dist <= maxDistance)
+    .sort((a, b) => a.dist - b.dist || a.name.localeCompare(b.name))
+    .slice(0, max)
+    .map((c) => c.name);
+}

package/src/list.mjs

@@ -3,6 +3,19 @@ import { existsSync } from "node:fs";
 import { resolve, relative } from "node:path";
 import { getRegistryRoot } from "./paths.mjs";
 
+export const HELP_TEXT = `sh-ui list — 현재 설치된 컴포넌트 목록 표시
+
+사용법:
+  sh-ui list
+
+옵션:
+  --all   설치되지 않은 컴포넌트까지 모두 표시
+
+예:
+  sh-ui list
+  sh-ui list --all
+`;
+
 function resolveDest(template, config) {
   return template.replace(/\{([a-zA-Z0-9_]+)\}/g, (m, key) => {
     const v = config.paths?.[key];

package/src/mcp.mjs

@@ -56,6 +56,20 @@ import { THEME_PRESET_NAMES } from "./create/theme/presets.js";
 import { decodeTheme } from "./create/theme/decode.js";
 import { encodeTheme } from "./create/theme/encode.js";
 
+export const HELP_TEXT = `sh-ui mcp — IDE-내 AI 용 MCP 서버 / 설정
+
+사용법:
+  sh-ui mcp                          MCP 서버(stdio) 시작
+  sh-ui mcp init --client <name>     IDE MCP 설정 파일에 sh-ui 엔트리 자동 추가
+
+옵션 (mcp init):
+  --client <name>   claude-code | cursor | claude-desktop | codex
+
+예:
+  sh-ui mcp
+  sh-ui mcp init --client claude-code
+`;
+
 const PLATFORMS = INIT_PLATFORMS;
 const BASES = THEME_BASES;
 const RADII = THEME_RADII;

package/src/migrate-bundled.mjs

@@ -16,6 +16,20 @@ import { existsSync } from "node:fs";
 import { resolve, relative, dirname, join } from "node:path";
 import { upsertSection, stripStylesImport } from "./css-bundle.mjs";
 
+export const HELP_TEXT = `sh-ui migrate bundled — cssStrategy=bundled 로 전환
+
+사용법:
+  sh-ui migrate bundled          per-component styles.css → 단일 sh-ui-components.css
+
+옵션:
+  --apply             실제 적용 (미지정 시 미리보기)
+  --bundle <path>     번들 CSS 파일 경로 명시
+
+예:
+  sh-ui migrate bundled
+  sh-ui migrate bundled --apply
+`;
+
 async function loadConfig(cwd) {
   const configPath = resolve(cwd, "sh-ui.config.json");
   if (!existsSync(configPath)) {

package/src/migrate-v065.mjs

@@ -14,6 +14,20 @@ import * as fsp from "node:fs/promises";
 import path from "node:path";
 import { createHash } from "node:crypto";
 
+export const HELP_TEXT = `sh-ui migrate-v065 — v0.64.x → v0.65 자동 마이그레이션
+
+사용법:
+  sh-ui migrate-v065             ui-app 컴포넌트를 ui-core 단일 SoT 로 dedup 이동
+
+옵션:
+  --dry-run   변경 plan 만 출력 (기본값 — 미지정 시 동작)
+  --apply     실제 적용
+
+예:
+  sh-ui migrate-v065
+  sh-ui migrate-v065 --apply
+`;
+
 const COMPONENT_KINDS = ["components", "hooks", "lib"];
 
 async function fileExists(p) {

package/src/remove.mjs

@@ -2,6 +2,21 @@ import { readFile, rm, rmdir, readdir, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { dirname, resolve, relative } from "node:path";
 import { getRegistryRoot } from "./paths.mjs";
+
+export const HELP_TEXT = `sh-ui remove — 설치된 컴포넌트 파일 삭제
+
+사용법:
+  sh-ui remove <component...>
+
+옵션:
+  --force     사용자가 수정한 파일도 삭제
+  --dry-run   변경 대상만 출력하고 실제로는 삭제하지 않음
+
+예:
+  sh-ui remove button
+  sh-ui remove button card --dry-run
+`;
+
 import {
   removeSection,
   isStyleFile,

package/src/rename-app.mjs

@@ -19,6 +19,21 @@ import { spawn } from "node:child_process";
 import { join, relative, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 
+export const HELP_TEXT = `sh-ui rename-app — monorepo 의 앱 이름 일괄 변경
+
+사용법:
+  sh-ui rename-app <old> <new>   apps/<old>/, ui-<old>/ 디렉토리 + 모든 import/path 패턴
+
+옵션:
+  --yes            대화형 확인 생략
+  --dry-run        변경 대상만 출력하고 실제로는 변경하지 않음
+  --skip-install   변경 후 pnpm install 생략
+
+예:
+  sh-ui rename-app web admin
+  sh-ui rename-app web admin --dry-run
+`;
+
 /** 텍스트 파일로 처리할 확장자 (전체 파일을 읽어 치환). */
 const TEXT_EXT = new Set([
   ".ts", ".tsx", ".js", ".mjs", ".cjs",

package/src/theme-extract.mjs

@@ -17,6 +17,19 @@ import { resolve, relative } from "node:path";
 import { parseBlocks } from "./tokens-diff.mjs";
 import { encodeTheme } from "./create/theme/encode.js";
 
+export const HELP_TEXT = `sh-ui theme — 현재 토큰을 테마 코드로 추출
+
+사용법:
+  sh-ui theme extract            tokens.css 의 색·radius 를 base64 로 추출 (stdout)
+
+옵션:
+  --out <path>   추출 결과를 stdout 대신 파일로 저장
+
+예:
+  sh-ui theme extract
+  sh-ui theme extract --out theme.txt
+`;
+
 /**
  * Dart 의 ShUiColorTokens 필드명 ↔ TOKEN_KEYS (hyphen) 매핑.
  * inject.js 의 DART_FIELD_SOURCES 와 같은 매핑을 reverse 로 사용.

package/src/tokens-cmd.mjs

@@ -17,6 +17,18 @@ import { THEME_BASES } from "./constants.js";
 import { parseBlocks, diffBlocks, applyAdditions } from "./tokens-diff.mjs";
 import { parseDartTokens, diffDartTokens } from "./tokens-diff-dart.mjs";
 
+export const HELP_TEXT = `sh-ui tokens — tokens.css 비교/업그레이드
+
+사용법:
+  sh-ui tokens diff                    tokens.css 와 buildTokens 결과 비교
+  sh-ui tokens upgrade --apply         추가된 변수만 적용 (사용자 편집 보존)
+  sh-ui tokens upgrade --replace       buildTokens 결과로 통째 덮어쓰기
+
+예:
+  sh-ui tokens diff
+  sh-ui tokens upgrade --apply
+`;
+
 async function loadTokensBuilder() {
   const url = pathToFileURL(resolve(getTokensRoot(), "build.mjs")).href;
   return import(url);

package/src/upgrade-cli.mjs

@@ -15,6 +15,19 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 
+export const HELP_TEXT = `sh-ui upgrade-cli — sh-ui-cli 자체를 최신으로 업그레이드
+
+사용법:
+  sh-ui upgrade-cli              최신 버전 확인 + 변경 내역 미리보기
+
+옵션:
+  --apply   실제 설치 후 진단 (미지정 시 미리보기만)
+
+예:
+  sh-ui upgrade-cli
+  sh-ui upgrade-cli --apply
+`;
+
 const CLI_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const REGISTRY_URL = "https://registry.npmjs.org/sh-ui-cli/latest";