sh-ui-cli 0.14.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SangHyeon Kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# sh-ui-cli
+
+sh-ui 디자인 시스템의 컴포넌트를 프로젝트로 복사하는 CLI. shadcn 방식 — 프로젝트가 소스를 소유한다.
+
+## 설치
+
+```bash
+# 프로젝트 dev 의존성으로
+npm i -D sh-ui-cli
+
+# 또는 ad-hoc 실행
+npx sh-ui-cli <command>
+```
+
+## 사용법
+
+### init — 설정 파일 생성
+
+```bash
+npx sh-ui init
+# 대화형 프롬프트:
+#   platform: react | flutter
+#   base:     neutral | zinc | slate
+#   radius:   none | sm | md | lg | xl | full
+#   mode:     light-dark | light | dark
+```
+
+비대화형 예:
+
+```bash
+npx sh-ui init --platform react --base neutral --radius md --mode light-dark --yes
+```
+
+### add — 컴포넌트 추가
+
+```bash
+npx sh-ui add button
+npx sh-ui add card input
+npx sh-ui add button --diff   # 파일 변경 미리보기(실제 쓰지 않음)
+```
+
+### list — 설치된 컴포넌트 목록
+
+```bash
+npx sh-ui list
+```
+
+### remove — 컴포넌트 제거
+
+```bash
+npx sh-ui remove button
+```
+
+## 지원 플랫폼
+
+- **React (Next.js)** — `src/shared/ui/` 또는 `sh-ui.config.json` 에 지정된 경로로 복사
+- **Flutter** — `lib/sh_ui/widgets/` 또는 지정 경로로 복사
+
+## 설정 파일 (`sh-ui.config.json`)
+
+```json
+{
+  "platform": "react",
+  "style": "default",
+  "theme": { "base": "neutral", "radius": "md", "mode": "light-dark" },
+  "paths": {
+    "tokens": "src/shared/styles/tokens.css",
+    "components": "src/shared/ui",
+    "utils": "src/shared/lib/utils.ts"
+  }
+}
+```
+
+## 더 알아보기
+
+- sh-ui 디자인 시스템: https://github.com/sanghyeonKim0201/sh-ui
+- `sh-ui-create` (프로젝트 스캐폴드): https://www.npmjs.com/package/sh-ui-create
+
+## 라이선스
+
+MIT

package/bin/sh-ui.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { init } from "../src/init.mjs";
+import { add } from "../src/add.mjs";
+import { list } from "../src/list.mjs";
+import { remove } from "../src/remove.mjs";
+
+const [, , cmd, ...rest] = process.argv;
+
+const usage = `사용법:
+  sh-ui init                       설정 파일(sh-ui.config.json) 생성
+  sh-ui add <component...>         컴포넌트 소스를 프로젝트로 복사하고
+                                   필요한 외부 패키지를 자동 설치
+                                   특수값: tokens → 설정 기반 토큰 파일 생성
+  sh-ui list                       현재 설치된 컴포넌트 목록 표시
+  sh-ui remove <component...>      설치된 컴포넌트 파일 삭제
+  옵션:
+    --skip-install                 (add) 외부 패키지 자동 설치 생략
+    --diff                         (add) 파일을 쓰지 않고 변경 내역만 출력
+    --all                          (list) 설치되지 않은 컴포넌트까지 표시
+    --force                        (remove) 사용자가 수정한 파일도 삭제
+    --dry-run                      (remove) 삭제 대상만 출력하고 실행 안 함
+`;
+
+try {
+  switch (cmd) {
+    case "init":
+      await init({ cwd: process.cwd(), args: rest });
+      break;
+    case "add": {
+      const skipInstall = rest.includes("--skip-install");
+      const diffMode = rest.includes("--diff");
+      const names = rest.filter((a) => !a.startsWith("--"));
+      if (names.length === 0) {
+        console.error("에러: 추가할 컴포넌트 이름이 필요합니다.\n");
+        console.error(usage);
+        process.exit(1);
+      }
+      await add({ cwd: process.cwd(), names, skipInstall, diffMode });
+      break;
+    }
+    case "list": {
+      const all = rest.includes("--all");
+      await list({ cwd: process.cwd(), all });
+      break;
+    }
+    case "remove":
+    case "rm": {
+      const force = rest.includes("--force");
+      const dryRun = rest.includes("--dry-run");
+      const names = rest.filter((a) => !a.startsWith("--"));
+      if (names.length === 0) {
+        console.error("에러: 삭제할 컴포넌트 이름이 필요합니다.\n");
+        console.error(usage);
+        process.exit(1);
+      }
+      await remove({ cwd: process.cwd(), names, force, dryRun });
+      break;
+    }
+    case undefined:
+    case "-h":
+    case "--help":
+      console.log(usage);
+      break;
+    default:
+      console.error(`알 수 없는 명령: ${cmd}\n`);
+      console.error(usage);
+      process.exit(1);
+  }
+} catch (err) {
+  console.error(`✗ ${err.message}`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "sh-ui-cli",
+  "version": "0.14.0",
+  "description": "sh-ui CLI — 디자인 시스템 컴포넌트를 프로젝트로 복사하는 CLI (sh-ui init / add / list / remove)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sanghyeonKim0201/sh-ui.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/sanghyeonKim0201/sh-ui#readme",
+  "bugs": {
+    "url": "https://github.com/sanghyeonKim0201/sh-ui/issues"
+  },
+  "keywords": [
+    "sh-ui",
+    "cli",
+    "design-system",
+    "registry",
+    "components"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "sh-ui": "./bin/sh-ui.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {}
+}

package/src/add.mjs

@@ -0,0 +1,280 @@
+import { readFile, writeFile, mkdir, copyFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, resolve, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { buildTokensCss, buildTokensDart } from "../../tokens/build.mjs";
+import { formatUnifiedDiff } from "./diff.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, "../../..");
+
+/** 컬러 출력 가능 여부: TTY + NO_COLOR 미설정. */
+function canUseColor() {
+  return Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+}
+
+/** `{components}/button.tsx` 처럼 config.paths 값으로 치환 */
+function resolveDest(template, config) {
+  return template.replace(/\{([a-zA-Z0-9_]+)\}/g, (m, key) => {
+    const v = config.paths?.[key];
+    if (!v) throw new Error(`paths.${key} 가 sh-ui.config.json에 없습니다.`);
+    return v;
+  });
+}
+
+async function ensureDir(filePath) {
+  await mkdir(dirname(filePath), { recursive: true });
+}
+
+/**
+ * 대상 파일 쓰기 래퍼. diff 모드면 기존 파일과 비교해 diff만 출력하고 skip.
+ * @returns "new" | "unchanged" | "modified" | "previewed"
+ */
+async function writeOrDiff({ dest, content, cwd, diffMode, summary, isBinary = false }) {
+  const rel = relative(cwd, dest);
+  const exists = existsSync(dest);
+
+  if (!exists) {
+    if (diffMode) {
+      summary.push({ kind: "new", rel });
+      return "previewed";
+    }
+    await ensureDir(dest);
+    await writeFile(dest, content, "utf8");
+    return "new";
+  }
+
+  if (isBinary) {
+    // 바이너리는 diff 의미가 없으므로 size만 비교
+    if (diffMode) {
+      summary.push({ kind: "binary", rel });
+      return "previewed";
+    }
+    await writeFile(dest, content, "utf8");
+    return "modified";
+  }
+
+  const existing = await readFile(dest, "utf8");
+  if (existing === content) {
+    if (diffMode) {
+      summary.push({ kind: "same", rel });
+    }
+    return "unchanged";
+  }
+
+  if (diffMode) {
+    const { text, addCount, delCount } = formatUnifiedDiff(existing, content, {
+      useColor: canUseColor(),
+    });
+    summary.push({ kind: "modified", rel, addCount, delCount, diff: text });
+    return "previewed";
+  }
+
+  await writeFile(dest, content, "utf8");
+  return "modified";
+}
+
+/** 특수 컴포넌트: 설정으로 토큰 파일 생성 */
+async function addTokens(config, cwd, diffMode, summary) {
+  const destRel = config.paths?.tokens;
+  if (!destRel) throw new Error("paths.tokens 가 설정에 없습니다.");
+  const dest = resolve(cwd, destRel);
+
+  const content =
+    config.platform === "react"
+      ? await buildTokensCss(config)
+      : await buildTokensDart(config);
+
+  const result = await writeOrDiff({ dest, content, cwd, diffMode, summary });
+  if (!diffMode && result !== "unchanged") {
+    console.log(`✓ tokens → ${relative(cwd, dest)}`);
+  }
+}
+
+async function addComponent(name, config, cwd, installed, pendingDeps, diffMode, summary) {
+  const registryPath = resolve(
+    REPO_ROOT,
+    "packages/registry",
+    config.platform,
+    "registry.json",
+  );
+  const registry = JSON.parse(await readFile(registryPath, "utf8"));
+  const entry = registry.components?.[name];
+  if (!entry) {
+    throw new Error(
+      `'${name}' 컴포넌트를 ${config.platform} 레지스트리에서 찾을 수 없습니다.`,
+    );
+  }
+
+  for (const dep of entry.registryDependencies ?? []) {
+    await addOne(dep, config, cwd, installed, pendingDeps, diffMode, summary);
+  }
+
+  for (const file of entry.files) {
+    const src = resolve(REPO_ROOT, "packages/registry", config.platform, file.src);
+    const dest = resolve(cwd, resolveDest(file.dest, config));
+    const content = await readFile(src, "utf8");
+    const result = await writeOrDiff({ dest, content, cwd, diffMode, summary });
+    if (!diffMode && result !== "unchanged") {
+      console.log(`✓ ${name} → ${relative(cwd, dest)}`);
+    }
+  }
+
+  for (const dep of entry.dependencies ?? []) {
+    pendingDeps.add(dep);
+  }
+}
+
+/** lockfile 존재로 패키지 매니저 감지. 없으면 npm. */
+function detectPackageManager(cwd) {
+  if (existsSync(resolve(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (
+    existsSync(resolve(cwd, "bun.lockb")) ||
+    existsSync(resolve(cwd, "bun.lock"))
+  ) {
+    return "bun";
+  }
+  if (existsSync(resolve(cwd, "yarn.lock"))) return "yarn";
+  return "npm";
+}
+
+/** 이미 package.json에 있는 의존성은 제외. */
+async function filterMissingDeps(deps, cwd) {
+  try {
+    const pkg = JSON.parse(
+      await readFile(resolve(cwd, "package.json"), "utf8"),
+    );
+    const have = {
+      ...(pkg.dependencies ?? {}),
+      ...(pkg.devDependencies ?? {}),
+      ...(pkg.peerDependencies ?? {}),
+      ...(pkg.optionalDependencies ?? {}),
+    };
+    return deps.filter((d) => !(d in have));
+  } catch {
+    return deps;
+  }
+}
+
+function runInstall(pm, deps, cwd) {
+  const addCmd = pm === "npm" ? "install" : "add";
+  const args = [addCmd, ...deps];
+  console.log(`\n외부 패키지 설치: ${pm} ${args.join(" ")}`);
+  // Windows는 .cmd/.bat 파일을 실행하려면 shell이 필요하지만,
+  // Unix에선 args 이스케이프 경고를 피하려고 shell을 끈다.
+  const isWin = process.platform === "win32";
+  return new Promise((ok, bad) => {
+    const child = spawn(pm, args, { cwd, stdio: "inherit", shell: isWin });
+    child.on("exit", (code) =>
+      code === 0 ? ok() : bad(new Error(`${pm} exited with code ${code}`)),
+    );
+    child.on("error", bad);
+  });
+}
+
+export async function add({ cwd, names, skipInstall = false, diffMode = false }) {
+  const configPath = resolve(cwd, "sh-ui.config.json");
+  let config;
+  try {
+    config = JSON.parse(await readFile(configPath, "utf8"));
+  } catch {
+    throw new Error(
+      "sh-ui.config.json을 찾을 수 없습니다. 먼저 `sh-ui init`을 실행하세요.",
+    );
+  }
+
+  const installed = new Set();
+  const pendingDeps = new Set();
+  const summary = [];
+  for (const name of names) {
+    await addOne(name, config, cwd, installed, pendingDeps, diffMode, summary);
+  }
+
+  if (diffMode) {
+    renderDiffReport(summary);
+    return;
+  }
+
+  if (pendingDeps.size === 0) return;
+
+  const deps = [...pendingDeps];
+  const missing = await filterMissingDeps(deps, cwd);
+
+  if (missing.length === 0) {
+    console.log(
+      `\n외부 패키지 모두 이미 설치됨: ${deps.join(", ")}`,
+    );
+    return;
+  }
+
+  if (skipInstall) {
+    const pm = detectPackageManager(cwd);
+    const addCmd = pm === "npm" ? "install" : "add";
+    console.log(
+      `\n  ⚠ 외부 패키지 필요. 다음을 실행하세요:\n    ${pm} ${addCmd} ${missing.join(" ")}`,
+    );
+    return;
+  }
+
+  const pm = detectPackageManager(cwd);
+  try {
+    await runInstall(pm, missing, cwd);
+  } catch (err) {
+    const addCmd = pm === "npm" ? "install" : "add";
+    console.error(
+      `\n✗ 자동 설치 실패 (${err.message}). 수동으로 실행하세요:\n    ${pm} ${addCmd} ${missing.join(" ")}`,
+    );
+    throw err;
+  }
+}
+
+async function addOne(name, config, cwd, installed, pendingDeps, diffMode, summary) {
+  if (installed.has(name)) return;
+  installed.add(name);
+  if (name === "tokens") {
+    await addTokens(config, cwd, diffMode, summary);
+  } else {
+    await addComponent(name, config, cwd, installed, pendingDeps, diffMode, summary);
+  }
+}
+
+function renderDiffReport(summary) {
+  const created = summary.filter((s) => s.kind === "new");
+  const modified = summary.filter((s) => s.kind === "modified");
+  const same = summary.filter((s) => s.kind === "same");
+  const binary = summary.filter((s) => s.kind === "binary");
+
+  console.log("\n── 변경 미리보기 (diff 모드) ──");
+
+  if (created.length) {
+    console.log(`\n신규 ${created.length}개:`);
+    for (const s of created) console.log(`  + ${s.rel}`);
+  }
+
+  if (modified.length) {
+    console.log(`\n변경 ${modified.length}개:`);
+    for (const s of modified) {
+      console.log(`\n  ~ ${s.rel} (+${s.addCount} -${s.delCount})`);
+      console.log(s.diff);
+    }
+  }
+
+  if (binary.length) {
+    console.log(`\n바이너리(비교 생략) ${binary.length}개:`);
+    for (const s of binary) console.log(`  ~ ${s.rel}`);
+  }
+
+  if (same.length) {
+    console.log(`\n동일(변경 없음) ${same.length}개:`);
+    for (const s of same) console.log(`  = ${s.rel}`);
+  }
+
+  if (!created.length && !modified.length) {
+    console.log("\n모든 파일이 최신 상태입니다.");
+  } else {
+    console.log(
+      "\n※ diff 모드 — 파일이 실제로 쓰이지 않았습니다. 적용하려면 --diff 없이 다시 실행하세요.",
+    );
+  }
+}

package/src/diff.mjs

@@ -0,0 +1,116 @@
+// 의존성 없는 라인 단위 unified-diff 생성기.
+// 컴포넌트 파일(~1000줄 이하)에 충분한 성능의 LCS-DP.
+
+/** LCS DP로 (=, -, +) 시퀀스를 만든다. */
+function lcsOps(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      if (a[i - 1] === b[j - 1]) dp[i][j] = dp[i - 1][j - 1] + 1;
+      else dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1]);
+    }
+  }
+  const ops = [];
+  let i = m;
+  let j = n;
+  while (i > 0 && j > 0) {
+    if (a[i - 1] === b[j - 1]) {
+      ops.unshift({ op: "=", line: a[i - 1] });
+      i--;
+      j--;
+    } else if (dp[i - 1][j] >= dp[i][j - 1]) {
+      ops.unshift({ op: "-", line: a[i - 1] });
+      i--;
+    } else {
+      ops.unshift({ op: "+", line: b[j - 1] });
+      j--;
+    }
+  }
+  while (i > 0) {
+    ops.unshift({ op: "-", line: a[i - 1] });
+    i--;
+  }
+  while (j > 0) {
+    ops.unshift({ op: "+", line: b[j - 1] });
+    j--;
+  }
+  return ops;
+}
+
+/** 터미널 컬러가 지원되면 ANSI 이스케이프, 아니면 평문. */
+function paint(useColor) {
+  if (!useColor) {
+    return {
+      red: (s) => s,
+      green: (s) => s,
+      dim: (s) => s,
+    };
+  }
+  return {
+    red: (s) => `\x1b[31m${s}\x1b[0m`,
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  };
+}
+
+/**
+ * 두 텍스트를 비교해 unified diff 문자열을 반환한다.
+ * context 줄은 `===`(동일 블록) 3개를 넘어가면 축약.
+ */
+export function formatUnifiedDiff(oldText, newText, { useColor = false, context = 3 } = {}) {
+  const oldLines = oldText.split("\n");
+  const newLines = newText.split("\n");
+  const ops = lcsOps(oldLines, newLines);
+
+  const c = paint(useColor);
+  const out = [];
+  let addCount = 0;
+  let delCount = 0;
+
+  // 변경이 있는 구간만 context 라인과 함께 출력
+  const changeIdx = [];
+  ops.forEach((o, idx) => {
+    if (o.op !== "=") changeIdx.push(idx);
+  });
+  if (changeIdx.length === 0) {
+    return { text: "", addCount: 0, delCount: 0 };
+  }
+
+  // 인접한 변경들을 그룹으로 묶어 context 범위 표시
+  const groups = [];
+  let cur = { start: Math.max(0, changeIdx[0] - context), end: changeIdx[0] + context };
+  for (let k = 1; k < changeIdx.length; k++) {
+    const idx = changeIdx[k];
+    if (idx - context <= cur.end) {
+      cur.end = Math.max(cur.end, idx + context);
+    } else {
+      groups.push(cur);
+      cur = { start: idx - context, end: idx + context };
+    }
+  }
+  groups.push(cur);
+
+  for (const g of groups) {
+    out.push(c.dim(`  @@ …`));
+    const from = Math.max(0, g.start);
+    const to = Math.min(ops.length - 1, g.end);
+    for (let idx = from; idx <= to; idx++) {
+      const o = ops[idx];
+      if (o.op === "=") out.push(`  ${o.line}`);
+      else if (o.op === "-") {
+        out.push(c.red(`- ${o.line}`));
+        delCount++;
+      } else {
+        out.push(c.green(`+ ${o.line}`));
+        addCount++;
+      }
+    }
+  }
+
+  // groups를 만들 때 delCount/addCount가 context에 걸친 실제 + / - 라인만 세도록 보정:
+  // 위 반복에서 동일한 인덱스의 - / +만 센 것이므로 일치한다. (중복 카운트 우려 없음)
+
+  return { text: out.join("\n"), addCount, delCount };
+}

package/src/init.mjs

@@ -0,0 +1,156 @@
+import { writeFile, access } from "node:fs/promises";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+
+const CHOICES = {
+  platform: ["react", "flutter"],
+  base: ["neutral", "zinc", "slate"],
+  radius: ["none", "sm", "md", "lg", "xl", "full"],
+  mode: ["light-dark", "light", "dark"],
+};
+
+const DEFAULTS = {
+  platform: "react",
+  base: "neutral",
+  radius: "md",
+  mode: "light-dark",
+};
+
+const PATHS = {
+  react: {
+    tokens: "src/styles/tokens.css",
+    components: "src/components/ui",
+    utils: "src/lib/utils.ts",
+  },
+  flutter: {
+    tokens: "lib/sh_ui/foundation/sh_ui_tokens.dart",
+    components: "lib/sh_ui/widgets",
+    foundation: "lib/sh_ui/foundation",
+    widgets: "lib/sh_ui/widgets",
+  },
+};
+
+const ALIASES = {
+  react: {
+    components: "@/components",
+    utils: "@/lib/utils",
+    ui: "@/components/ui",
+  },
+};
+
+/** --key=value / --key value / -y / --yes / --force 파싱 */
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "-y" || a === "--yes") flags.yes = true;
+    else if (a === "--force") flags.force = true;
+    else if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq > -1) flags[a.slice(2, eq)] = a.slice(eq + 1);
+      else flags[a.slice(2)] = args[++i];
+    }
+  }
+  return flags;
+}
+
+async function exists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** TTY 대화형 프롬프트. 잘못된 값이면 재질문. 빈 입력은 기본값. */
+async function prompt(rl, label, choices, def) {
+  while (true) {
+    const raw = (await rl.question(`${label} [${choices.join("/")}] (${def}): `))
+      .trim()
+      .toLowerCase();
+    const value = raw || def;
+    if (choices.includes(value)) return value;
+    console.log(`  ! '${raw}'는 허용되지 않습니다. 다시 입력하세요.`);
+  }
+}
+
+function validateOrThrow(key, value) {
+  if (!CHOICES[key].includes(value)) {
+    throw new Error(
+      `--${key}에 '${value}'는 허용되지 않습니다. 허용: ${CHOICES[key].join(", ")}`,
+    );
+  }
+}
+
+/** 플래그/TTY 상태에 따라 4개 축 값을 결정. 필요한 경우에만 프롬프트. */
+async function resolveAnswers(flags) {
+  const answers = { ...DEFAULTS };
+  for (const key of Object.keys(CHOICES)) {
+    if (flags[key] != null) {
+      validateOrThrow(key, flags[key]);
+      answers[key] = flags[key];
+    }
+  }
+
+  const missingKeys = Object.keys(CHOICES).filter((k) => flags[k] == null);
+  if (flags.yes || missingKeys.length === 0) return answers;
+
+  if (!stdin.isTTY) {
+    throw new Error(
+      `비-TTY 환경에서는 프롬프트를 쓸 수 없습니다. --yes 또는 플래그로 값을 지정하세요.\n` +
+        `예: sh-ui init --platform react --base neutral --radius md --mode light-dark`,
+    );
+  }
+
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    console.log("sh-ui Design System 설정을 시작합니다. (Enter = 기본값)\n");
+    for (const key of missingKeys) {
+      answers[key] = await prompt(rl, labelFor(key), CHOICES[key], answers[key]);
+    }
+  } finally {
+    rl.close();
+  }
+  return answers;
+}
+
+function labelFor(key) {
+  return {
+    platform: "플랫폼",
+    base: "기본 색 스케일",
+    radius: "radius",
+    mode: "모드",
+  }[key];
+}
+
+function buildConfig({ platform, base, radius, mode }) {
+  return {
+    $schema: "https://your-ds.dev/sh-ui.schema.json",
+    platform,
+    style: "default",
+    theme: { base, radius, mode },
+    paths: PATHS[platform],
+    ...(ALIASES[platform] ? { aliases: ALIASES[platform] } : {}),
+  };
+}
+
+export async function init({ cwd, args }) {
+  const flags = parseFlags(args);
+  const configPath = resolve(cwd, "sh-ui.config.json");
+
+  if ((await exists(configPath)) && !flags.force) {
+    throw new Error("sh-ui.config.json이 이미 존재합니다. --force로 덮어쓰기 가능.");
+  }
+
+  const answers = await resolveAnswers(flags);
+  const config = buildConfig(answers);
+
+  await writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+
+  console.log(`\n✓ sh-ui.config.json 생성 완료`);
+  console.log(`  platform: ${answers.platform}`);
+  console.log(`  theme:    base=${answers.base}, radius=${answers.radius}, mode=${answers.mode}`);
+  console.log(`\n다음 단계:  sh-ui add tokens button`);
+}

package/src/list.mjs

@@ -0,0 +1,89 @@
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, resolve, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, "../../..");
+
+function resolveDest(template, config) {
+  return template.replace(/\{([a-zA-Z0-9_]+)\}/g, (m, key) => {
+    const v = config.paths?.[key];
+    if (!v) throw new Error(`paths.${key} 가 sh-ui.config.json에 없습니다.`);
+    return v;
+  });
+}
+
+async function loadConfig(cwd) {
+  const configPath = resolve(cwd, "sh-ui.config.json");
+  try {
+    return JSON.parse(await readFile(configPath, "utf8"));
+  } catch {
+    throw new Error(
+      "sh-ui.config.json을 찾을 수 없습니다. 먼저 `sh-ui init`을 실행하세요.",
+    );
+  }
+}
+
+async function loadRegistry(platform) {
+  const registryPath = resolve(
+    REPO_ROOT,
+    "packages/registry",
+    platform,
+    "registry.json",
+  );
+  return JSON.parse(await readFile(registryPath, "utf8"));
+}
+
+/** 해당 컴포넌트의 파일 중 하나라도 존재하면 "설치됨"으로 간주. */
+function isInstalled(entry, config, cwd) {
+  for (const file of entry.files) {
+    const dest = resolve(cwd, resolveDest(file.dest, config));
+    if (existsSync(dest)) return true;
+  }
+  return false;
+}
+
+export async function list({ cwd, all = false }) {
+  const config = await loadConfig(cwd);
+  const registry = await loadRegistry(config.platform);
+  const entries = Object.entries(registry.components ?? {});
+
+  const rows = [];
+  for (const [name, entry] of entries) {
+    try {
+      rows.push({
+        name,
+        installed: isInstalled(entry, config, cwd),
+        files: entry.files.map((f) => resolveDest(f.dest, config)),
+      });
+    } catch {
+      // 이 config에서 해석 불가한 paths placeholder가 있는 엔트리는 스킵
+      // (예: base.css는 {styles} 경로를 쓰는데 기본 config엔 paths.styles 없음)
+    }
+  }
+
+  const installed = rows.filter((r) => r.installed);
+  const available = rows.filter((r) => !r.installed);
+
+  console.log(`플랫폼: ${config.platform}\n`);
+
+  if (installed.length === 0) {
+    console.log("설치된 컴포넌트 없음. `sh-ui add <name>`으로 시작하세요.");
+  } else {
+    console.log(`설치됨 (${installed.length}개):`);
+    for (const r of installed) {
+      console.log(`  ✓ ${r.name}`);
+      for (const f of r.files) console.log(`      ${relative(cwd, resolve(cwd, f))}`);
+    }
+  }
+
+  if (all) {
+    console.log(`\n설치 가능 (${available.length}개):`);
+    for (const r of available) console.log(`  · ${r.name}`);
+  } else if (available.length > 0) {
+    console.log(
+      `\n설치 가능한 컴포넌트 ${available.length}개 더 있음. 전체 목록은 \`sh-ui list --all\`.`,
+    );
+  }
+}

package/src/remove.mjs

@@ -0,0 +1,146 @@
+import { readFile, rm, rmdir, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, resolve, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, "../../..");
+
+function resolveDest(template, config) {
+  return template.replace(/\{([a-zA-Z0-9_]+)\}/g, (m, key) => {
+    const v = config.paths?.[key];
+    if (!v) throw new Error(`paths.${key} 가 sh-ui.config.json에 없습니다.`);
+    return v;
+  });
+}
+
+async function loadConfig(cwd) {
+  const configPath = resolve(cwd, "sh-ui.config.json");
+  try {
+    return JSON.parse(await readFile(configPath, "utf8"));
+  } catch {
+    throw new Error(
+      "sh-ui.config.json을 찾을 수 없습니다. 먼저 `sh-ui init`을 실행하세요.",
+    );
+  }
+}
+
+async function loadRegistry(platform) {
+  const registryPath = resolve(
+    REPO_ROOT,
+    "packages/registry",
+    platform,
+    "registry.json",
+  );
+  return JSON.parse(await readFile(registryPath, "utf8"));
+}
+
+/** 설치된 파일이 레지스트리 원본과 동일한지(= 사용자가 수정하지 않았는지). */
+async function isUnmodified(srcAbs, destAbs) {
+  try {
+    const [src, dest] = await Promise.all([
+      readFile(srcAbs, "utf8"),
+      readFile(destAbs, "utf8"),
+    ]);
+    return src === dest;
+  } catch {
+    return false;
+  }
+}
+
+/** 디렉터리가 비어 있으면 지운다. 상위로 올라가며 반복. */
+async function pruneEmptyDirs(startDir, stopAt) {
+  let dir = startDir;
+  while (dir.startsWith(stopAt) && dir !== stopAt) {
+    try {
+      const entries = await readdir(dir);
+      if (entries.length > 0) return;
+      await rmdir(dir);
+    } catch {
+      return;
+    }
+    dir = dirname(dir);
+  }
+}
+
+export async function remove({ cwd, names, force = false, dryRun = false }) {
+  const config = await loadConfig(cwd);
+  const registry = await loadRegistry(config.platform);
+
+  const plannedDeletes = [];
+  const modifiedBlocked = [];
+  const missingNames = [];
+
+  for (const name of names) {
+    const entry = registry.components?.[name];
+    if (!entry) {
+      missingNames.push(name);
+      continue;
+    }
+
+    for (const file of entry.files) {
+      const srcAbs = resolve(REPO_ROOT, "packages/registry", config.platform, file.src);
+      const destAbs = resolve(cwd, resolveDest(file.dest, config));
+
+      if (!existsSync(destAbs)) continue;
+
+      const unmodified = await isUnmodified(srcAbs, destAbs);
+      if (!unmodified && !force) {
+        modifiedBlocked.push({ name, dest: destAbs });
+        continue;
+      }
+      plannedDeletes.push({ name, dest: destAbs, unmodified });
+    }
+  }
+
+  if (missingNames.length > 0) {
+    for (const n of missingNames) {
+      console.error(`✗ '${n}' 은(는) ${config.platform} 레지스트리에 없습니다.`);
+    }
+  }
+
+  if (modifiedBlocked.length > 0) {
+    console.error("\n⚠ 사용자가 수정한 파일이 있어 삭제를 건너뜁니다:");
+    for (const f of modifiedBlocked) {
+      console.error(`    ${relative(cwd, f.dest)}  (${f.name})`);
+    }
+    console.error(
+      "\n  --force 를 붙이면 수정된 파일도 삭제합니다. (원본 복구 불가)",
+    );
+  }
+
+  if (plannedDeletes.length === 0) {
+    if (modifiedBlocked.length > 0 || missingNames.length > 0) {
+      process.exit(1);
+    }
+    console.log("삭제할 파일이 없습니다.");
+    return;
+  }
+
+  if (dryRun) {
+    console.log("\n── 삭제 미리보기 (dry-run) ──");
+    for (const d of plannedDeletes) {
+      const tag = d.unmodified ? "" : " ⚠ 수정됨";
+      console.log(`  - ${relative(cwd, d.dest)}${tag}`);
+    }
+    console.log("\n실제로 삭제하려면 --dry-run 없이 다시 실행.");
+    return;
+  }
+
+  const touchedDirs = new Set();
+  for (const d of plannedDeletes) {
+    await rm(d.dest);
+    console.log(`✓ 삭제: ${relative(cwd, d.dest)}`);
+    touchedDirs.add(dirname(d.dest));
+  }
+
+  // 컴포넌트 폴더가 비면 정리 (paths.components 상위까지)
+  const componentsRoot = config.paths?.components
+    ? resolve(cwd, config.paths.components)
+    : cwd;
+  for (const dir of touchedDirs) {
+    await pruneEmptyDirs(dir, componentsRoot);
+  }
+
+  if (missingNames.length > 0 || modifiedBlocked.length > 0) process.exit(1);
+}