sh-ui-cli 0.115.0 → 0.116.0

package/bin/sh-ui.mjs

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
-import { init } from "../src/init.mjs";
+import { init, HELP_TEXT as INIT_HELP } from "../src/init.mjs";
 import { add } from "../src/add.mjs";
 import { list } from "../src/list.mjs";
 import { remove } from "../src/remove.mjs";
 import { findShUiContext } from "../src/resolve-context.mjs";
+import { suggest } from "../src/levenshtein.mjs";
+import { KNOWN_COMMANDS } from "../src/commands.mjs";
 
 const [, , cmd, ...rest] = process.argv;
 
@@ -36,6 +38,9 @@ const usage = `사용법:
   sh-ui mcp                        MCP 서버(stdio) 시작 — IDE-내 AI용
   sh-ui mcp init --client <name>   IDE MCP 설정 파일에 sh-ui 엔트리 자동 추가
                                    (claude-code | cursor | claude-desktop | codex)
+
+  각 명령의 상세 옵션은 \`sh-ui <command> --help\` 로 확인.
+
   옵션:
     --skip-install                 (add, rename-app) 외부 패키지 자동 설치 생략
     --diff                         (add) 파일을 쓰지 않고 변경 내역만 출력
@@ -57,9 +62,18 @@ try {
       break;
     }
     case "init":
+      if (rest.includes("--help") || rest.includes("-h")) {
+        console.log(INIT_HELP);
+        break;
+      }
       await init({ cwd: process.cwd(), args: rest });
       break;
     case "add": {
+      if (rest.includes("--help") || rest.includes("-h")) {
+        const { HELP_TEXT } = await import("../src/add.mjs");
+        console.log(HELP_TEXT);
+        break;
+      }
       const skipInstall = rest.includes("--skip-install");
       const diffMode = rest.includes("--diff");
       const force = rest.includes("--force");
@@ -107,11 +121,21 @@ try {
       break;
     }
     case "list": {
+      if (rest.includes("--help") || rest.includes("-h")) {
+        const { HELP_TEXT } = await import("../src/list.mjs");
+        console.log(HELP_TEXT);
+        break;
+      }
       const all = rest.includes("--all");
       await list({ cwd: process.cwd(), all });
       break;
     }
     case "doctor": {
+      if (rest.includes("--help") || rest.includes("-h")) {
+        const { HELP_TEXT } = await import("../src/doctor.mjs");
+        console.log(HELP_TEXT);
+        break;
+      }
       const { doctor } = await import("../src/doctor.mjs");
       const { existsSync, readdirSync } = await import("node:fs");
       const { resolve } = await import("node:path");
@@ -157,12 +181,22 @@ try {
       break;
     }
     case "upgrade-cli": {
+      if (rest.includes("--help") || rest.includes("-h")) {
+        const { HELP_TEXT } = await import("../src/upgrade-cli.mjs");
+        console.log(HELP_TEXT);
+        break;
+      }
       const apply = rest.includes("--apply");
       const { runUpgradeCli } = await import("../src/upgrade-cli.mjs");
       await runUpgradeCli({ cwd: process.cwd(), apply });
       break;
     }
     case "theme": {
+      if (rest.includes("--help") || rest.includes("-h")) {
+        const { HELP_TEXT } = await import("../src/theme-extract.mjs");
+        console.log(HELP_TEXT);
+        break;
+      }
       const sub = rest[0];
       const flags = rest.slice(1);
       if (sub === "extract") {
@@ -177,6 +211,11 @@ try {
       break;
     }
     case "tokens": {
+      if (rest.includes("--help") || rest.includes("-h")) {
+        const { HELP_TEXT } = await import("../src/tokens-cmd.mjs");
+        console.log(HELP_TEXT);
+        break;
+      }
       // sh-ui tokens diff
       // sh-ui tokens upgrade --apply | --replace
       const sub = rest[0];
@@ -210,6 +249,12 @@ try {
     case "mcp": {
       // `sh-ui mcp init ...` → 설정 파일에 엔트리 추가
       // `sh-ui mcp`         → MCP 서버 시작
+      // 단, `sh-ui mcp --help` 는 mcp HELP_TEXT 출력 (mcp init 의 인자 처리는 mcp-init.mjs 가 담당).
+      if (rest[0] !== "init" && (rest.includes("--help") || rest.includes("-h"))) {
+        const { HELP_TEXT } = await import("../src/mcp.mjs");
+        console.log(HELP_TEXT);
+        break;
+      }
       if (rest[0] === "init") {
         const { mcpInit } = await import("../src/mcp-init.mjs");
         await mcpInit({ cwd: process.cwd(), args: rest.slice(1) });
@@ -220,6 +265,11 @@ try {
       break;
     }
     case "rename-app": {
+      if (rest.includes("--help") || rest.includes("-h")) {
+        const { HELP_TEXT } = await import("../src/rename-app.mjs");
+        console.log(HELP_TEXT);
+        break;
+      }
       const yes = rest.includes("--yes");
       const dryRun = rest.includes("--dry-run");
       const skipInstall = rest.includes("--skip-install");
@@ -235,6 +285,11 @@ try {
       break;
     }
     case "migrate": {
+      if (rest.includes("--help") || rest.includes("-h")) {
+        const { HELP_TEXT } = await import("../src/migrate-bundled.mjs");
+        console.log(HELP_TEXT);
+        break;
+      }
       // sh-ui migrate bundled [--apply] [--bundle <path>]
       const sub = rest[0];
       const flags = rest.slice(1);
@@ -251,6 +306,11 @@ try {
       break;
     }
     case "migrate-v065": {
+      if (rest.includes("--help") || rest.includes("-h")) {
+        const { HELP_TEXT } = await import("../src/migrate-v065.mjs");
+        console.log(HELP_TEXT);
+        break;
+      }
       const apply = rest.includes("--apply");
       const skipImportRewrite = rest.includes("--skip-import-rewrite");
       const { migrateToV065 } = await import("../src/migrate-v065.mjs");
@@ -264,6 +324,11 @@ try {
     }
     case "remove":
     case "rm": {
+      if (rest.includes("--help") || rest.includes("-h")) {
+        const { HELP_TEXT } = await import("../src/remove.mjs");
+        console.log(HELP_TEXT);
+        break;
+      }
       const force = rest.includes("--force");
       const dryRun = rest.includes("--dry-run");
       const names = rest.filter((a) => !a.startsWith("--"));
@@ -280,10 +345,12 @@ try {
     case "--help":
       console.log(usage);
       break;
-    default:
-      console.error(`알 수 없는 명령: ${cmd}\n`);
+    default: {
+      const hits = suggest(cmd, KNOWN_COMMANDS);
+      console.error(`알 수 없는 명령: ${cmd}` + (hits.length ? ` — 혹시 ${hits.join(", ")}?` : "") + "\n");
       console.error(usage);
       process.exit(1);
+    }
   }
 } catch (err) {
   console.error(`✗ ${err.message}`);

package/data/changelog/versions.json

@@ -2,6 +2,18 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.116.0",
+      "date": "2026-06-17",
+      "title": "CLI 발견성 — 서브명령 --help + 오타 추천",
+      "type": "minor",
+      "highlights": [
+        "모든 서브명령에 --help — init·add·remove·doctor·tokens·theme·migrate·rename-app·upgrade-cli·mcp 전용 도움말",
+        "did-you-mean — 없는 컴포넌트/명령 입력 시 가까운 후보를 '혹시 …?' 로 제안",
+        "의존성 없는 levenshtein 유틸 내장 (packages/cli/src/levenshtein.mjs)"
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.116.0"
+    },
     {
       "version": "0.115.0",
       "date": "2026-06-01",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh-ui-cli",
-  "version": "0.115.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";