@seed-design/cli 1.2.0 → 1.2.2

package/src/commands/add.ts

@@ -11,6 +11,18 @@ import { BASE_URL } from "../constants";
 import { highlight } from "../utils/color";
 import { installDependencies } from "../utils/install";
 import { analytics } from "../utils/analytics";
+import {
+  analyzeRegistryItemCompatibility,
+  getProjectSeedPackageVersionSpecs,
+  logCompatibilityReport,
+} from "../utils/compatibility";
+import {
+  CliCancelError,
+  CliError,
+  handleCliError,
+  isCliCancelError,
+  isVerboseMode,
+} from "../utils/error";
 
 const addOptionsSchema = z.object({
   itemIds: z.array(z.string()).optional(),
@@ -20,7 +32,7 @@ const addOptionsSchema = z.object({
   all: z.boolean(),
   cwd: z.string(),
   baseUrl: z.string().optional(),
-  overwrite: z.boolean().optional(),
+  onDiff: z.enum(["overwrite", "backup"]).optional(),
 });
 
 export const addCommand = (cli: CAC) => {
@@ -37,157 +49,173 @@ export const addCommand = (cli: CAC) => {
       "the base url of the registry. defaults to the current directory.",
       { default: BASE_URL },
     )
-    .option("--overwrite", "Overwrite existing files without confirmation", {
-      default: false,
-    })
+    .option("--on-diff <mode>", "Action when file differs: overwrite or backup")
     .example("seed-design add ui:action-button")
     .example("seed-design add ui:alert-dialog")
     .action(async (itemIds, opts) => {
       const startTime = Date.now();
+      const verbose = isVerboseMode(opts);
       p.intro("seed-design add");
 
-      const {
-        success,
-        data: { all, ...options },
-        error,
-      } = addOptionsSchema.safeParse({ itemIds, ...opts });
+      try {
+        const parsed = addOptionsSchema.safeParse({ itemIds, ...opts });
+        if (!parsed.success) {
+          throw parsed.error;
+        }
 
-      if (!success) {
-        p.log.error(`잘못된 옵션이에요: ${error?.message}`);
+        const {
+          data: { all, ...options },
+        } = parsed;
 
-        process.exit(1);
-      }
+        if (all) {
+          throw new CliError({
+            message:
+              "`--all` 옵션은 더 이상 지원되지 않아요. 대신 `seed-design add-all` 명령어를 사용해주세요.",
+          });
+        }
 
-      if (all) {
-        p.log.error(
-          "`--all` 옵션은 더 이상 지원되지 않아요. 대신 `seed-design add-all` 명령어를 사용해주세요.",
-        );
+        const cwd = options.cwd;
+        const baseUrl = options.baseUrl;
+        const config = await getConfig(cwd);
+        const rootPath = path.resolve(cwd, config.path);
 
-        process.exit(1);
-      }
+        const { start, stop } = p.spinner();
+        start("Registry를 가져오고 있어요...");
 
-      const cwd = options.cwd;
-      const baseUrl = options.baseUrl;
-      const config = await getConfig(cwd);
-      const rootPath = path.resolve(cwd, config.path);
-
-      const { start, stop } = p.spinner();
-
-      start("Registry를 가져오고 있어요...");
-
-      const publicRegistries = await Promise.all(
-        (await fetchAvailableRegistries({ baseUrl })).map(async ({ id }) =>
-          fetchRegistry({ baseUrl, registryId: id }),
-        ),
-      );
-
-      stop("Registry를 가져왔어요.");
-
-      const selectedItemKeys: string[] = await (async () => {
-        if (options.itemIds.length > 0) return options.itemIds;
-
-        const selected = await p.multiselect({
-          message: "추가할 항목을 선택해주세요 (스페이스 바로 여러 개 선택 가능)",
-          options: publicRegistries
-            .filter(({ hideFromCLICatalog }) => !hideFromCLICatalog)
-            .flatMap(({ id: registryId, items }) =>
-              items
-                .filter(({ hideFromCLICatalog }) => !hideFromCLICatalog)
-                .sort((a, b) => a.id.localeCompare(b.id))
-                .map(({ id, description, deprecated }) => ({
-                  label: `${deprecated ? "(deprecated) " : ""}${highlight(registryId)}:${id}`,
-                  value: `${registryId}:${id}`,
-                  hint: description,
-
-                  // used for sorting
-                  deprecated,
-                  registryItemCount: items.length,
-                })),
-            )
-            .sort((a, b) => {
-              if (a.deprecated !== b.deprecated) return a.deprecated ? 1 : -1;
-
-              return b.registryItemCount - a.registryItemCount;
-            }),
-        });
+        const publicRegistries = await (async () => {
+          try {
+            const registries = await Promise.all(
+              (await fetchAvailableRegistries({ baseUrl })).map(async ({ id }) =>
+                fetchRegistry({ baseUrl, registryId: id }),
+              ),
+            );
+            stop("Registry를 가져왔어요.");
 
-        if (p.isCancel(selected)) {
-          p.log.error("취소되었어요.");
-          process.exit(0);
-        }
+            return registries;
+          } catch (error) {
+            stop("Registry를 가져오지 못했어요.");
+            throw error;
+          }
+        })();
 
-        return selected;
-      })();
+        const selectedItemKeys: string[] = await (async () => {
+          if (options.itemIds?.length) {
+            return options.itemIds;
+          }
 
-      if (!selectedItemKeys?.length) {
-        p.log.error("항목을 찾을 수 없어요.");
+          const selected = await p.multiselect({
+            message: "추가할 항목을 선택해주세요 (스페이스 바로 여러 개 선택 가능)",
+            options: publicRegistries
+              .filter(({ hideFromCLICatalog }) => !hideFromCLICatalog)
+              .flatMap(({ id: registryId, items }) =>
+                items
+                  .filter(({ hideFromCLICatalog }) => !hideFromCLICatalog)
+                  .sort((a, b) => a.id.localeCompare(b.id))
+                  .map(({ id, description, deprecated }) => ({
+                    label: `${deprecated ? "(deprecated) " : ""}${highlight(registryId)}:${id}`,
+                    value: `${registryId}:${id}`,
+                    hint: description,
+
+                    // used for sorting
+                    deprecated,
+                    registryItemCount: items.length,
+                  })),
+              )
+              .sort((a, b) => {
+                if (a.deprecated !== b.deprecated) return a.deprecated ? 1 : -1;
+
+                return b.registryItemCount - a.registryItemCount;
+              }),
+          });
 
-        process.exit(0);
-      }
+          if (p.isCancel(selected)) {
+            throw new CliCancelError();
+          }
 
-      p.log.message(`선택된 항목: ${highlight(selectedItemKeys.join(", "))}`);
+          return selected;
+        })();
 
-      const filteredItemKeys: string[] = [];
+        if (!selectedItemKeys?.length) {
+          throw new CliCancelError("추가할 항목이 선택되지 않았어요.");
+        }
 
-      for (const itemKey of selectedItemKeys) {
-        const [registryId, ...rest] = itemKey.split(":");
-        const itemId = rest.join(":");
+        p.log.message(`선택된 항목: ${highlight(selectedItemKeys.join(", "))}`);
 
-        if (!registryId || !itemId) {
-          p.log.error(
-            `${highlight(itemKey)}: 항목 이름이 잘못되었어요. ${highlight("ui:action-button")}과 같은 형식으로 입력해보세요.`,
-          );
+        const filteredItemKeys: string[] = [];
 
-          process.exit(1);
-        }
+        for (const itemKey of selectedItemKeys) {
+          const [registryId, ...rest] = itemKey.split(":");
+          const itemId = rest.join(":");
 
-        const foundItem = publicRegistries
-          .find((r) => r.id === registryId)
-          ?.items.find((i) => i.id === itemId);
+          if (!registryId || !itemId) {
+            throw new CliError({
+              message: `${highlight(itemKey)}: 항목 이름이 잘못되었어요.`,
+              hint: `${highlight("ui:action-button")}과 같은 형식으로 입력해보세요.`,
+            });
+          }
 
-        if (!foundItem) {
-          p.log.error(`${highlight(itemKey)}: 항목을 찾을 수 없어요.`);
+          const foundItem = publicRegistries
+            .find((r) => r.id === registryId)
+            ?.items.find((i) => i.id === itemId);
 
-          process.exit(1);
-        }
+          if (!foundItem) {
+            throw new CliError({
+              message: `${highlight(itemKey)}: 항목을 찾을 수 없어요.`,
+            });
+          }
 
-        if (foundItem.deprecated) {
-          const confirm = await p.confirm({
-            message: `${highlight(foundItem.id)}: deprecated 되었어요. 추가할까요?`,
-            initialValue: false,
-          });
+          if (foundItem.deprecated) {
+            const confirm = await p.confirm({
+              message: `${highlight(foundItem.id)}: deprecated 되었어요. 추가할까요?`,
+              initialValue: false,
+            });
 
-          if (confirm === false || p.isCancel(confirm)) {
-            p.log.info(`${highlight(foundItem.id)}: 추가하지 않을게요.`);
+            if (p.isCancel(confirm)) {
+              throw new CliCancelError();
+            }
 
-            continue;
+            if (confirm === false) {
+              p.log.info(`${highlight(foundItem.id)}: 추가하지 않을게요.`);
+              continue;
+            }
           }
+
+          filteredItemKeys.push(itemKey);
         }
 
-        filteredItemKeys.push(itemKey);
-      }
+        const { registryItemsToAdd, npmDependenciesToAdd } = resolveDependencies({
+          selectedItemKeys: filteredItemKeys,
+          publicRegistries,
+        });
+
+        const compatibilityReport = analyzeRegistryItemCompatibility({
+          publicRegistries,
+          itemKeys: registryItemsToAdd.flatMap(({ registryId, items }) =>
+            items.map((item) => `${registryId}:${item.id}`),
+          ),
+          projectPackageVersions: getProjectSeedPackageVersionSpecs(options.cwd),
+        });
 
-      const { registryItemsToAdd, npmDependenciesToAdd } = resolveDependencies({
-        selectedItemKeys: filteredItemKeys,
-        publicRegistries,
-      });
+        logCompatibilityReport({
+          report: compatibilityReport,
+          title: "현재 프로젝트 버전과 호환되지 않을 수 있는 스니펫이 있어요.",
+        });
 
-      p.log.info(
-        `추가할 항목: ${highlight(registryItemsToAdd.map((r) => r.items.map((i) => `${r.registryId}:${i.id}`).join(", ")).join(", ") || "없음")}
+        p.log.info(
+          `추가할 항목: ${highlight(registryItemsToAdd.map((r) => r.items.map((i) => `${r.registryId}:${i.id}`).join(", ")).join(", ") || "없음")}
 
 설치할 의존성: ${highlight(Array.from(npmDependenciesToAdd).join(", ") || "없음")}`,
-      );
+        );
 
-      await writeRegistryItemSnippets({
-        registryItemsToAdd,
-        rootPath,
-        cwd,
-        baseUrl,
-        config,
-        overwrite: options.overwrite,
-      });
+        await writeRegistryItemSnippets({
+          registryItemsToAdd,
+          rootPath,
+          cwd,
+          baseUrl,
+          config,
+          onDiff: options.onDiff,
+        });
 
-      try {
         const { installed, filtered } = await installDependencies({
           cwd,
           deps: Array.from(npmDependenciesToAdd),
@@ -207,31 +235,46 @@ export const addCommand = (cli: CAC) => {
           }
         }
         p.outro("완료했어요.");
+
+        // add 성공 이벤트 추적
+        const duration = Date.now() - startTime;
+        const uniqueRegistries = new Set(registryItemsToAdd.map((r) => r.registryId));
+        const hasDeprecated = selectedItemKeys.some((itemKey) => {
+          const [registryId, ...rest] = itemKey.split(":");
+          const itemId = rest.join(":");
+          return publicRegistries
+            .find((r) => r.id === registryId)
+            ?.items.find((i) => i.id === itemId)?.deprecated;
+        });
+
+        try {
+          await analytics.track(options.cwd, {
+            event: "add",
+            properties: {
+              items_count: filteredItemKeys.length,
+              registries: Array.from(uniqueRegistries),
+              has_deprecated: hasDeprecated,
+              dependencies_count: npmDependenciesToAdd.size,
+              duration_ms: duration,
+            },
+          });
+        } catch (telemetryError) {
+          if (verbose) {
+            console.error("[Telemetry] add tracking failed:", telemetryError);
+          }
+        }
       } catch (error) {
-        p.log.error(`추가에 실패했어요. ${error}`);
-        p.outro(highlight("작업이 취소됐어요."));
+        if (isCliCancelError(error)) {
+          p.outro(highlight(error.message));
+          process.exit(0);
+        }
+
+        handleCliError(error, {
+          defaultMessage: "추가에 실패했어요.",
+          defaultHint: "`--verbose` 옵션으로 상세 오류를 확인해보세요.",
+          verbose,
+        });
         process.exit(1);
       }
-
-      // add 성공 이벤트 추적
-      const duration = Date.now() - startTime;
-      const uniqueRegistries = new Set(registryItemsToAdd.map((r) => r.registryId));
-      const hasDeprecated = selectedItemKeys.some((itemKey) => {
-        const [registryId, ...rest] = itemKey.split(":");
-        const itemId = rest.join(":");
-        return publicRegistries.find((r) => r.id === registryId)?.items.find((i) => i.id === itemId)
-          ?.deprecated;
-      });
-
-      await analytics.track(options.cwd, {
-        event: "add",
-        properties: {
-          items_count: filteredItemKeys.length,
-          registries: Array.from(uniqueRegistries),
-          has_deprecated: hasDeprecated,
-          dependencies_count: npmDependenciesToAdd.size,
-          duration_ms: duration,
-        },
-      });
     });
 };

package/src/commands/compat.ts

@@ -0,0 +1,281 @@
+import { fetchAvailableRegistries, fetchRegistry } from "@/src/utils/fetch";
+import { getRawConfig } from "@/src/utils/get-config";
+import * as p from "@clack/prompts";
+import path from "path";
+import { z } from "zod";
+
+import type { CAC } from "cac";
+import { BASE_URL } from "../constants";
+import { analytics } from "../utils/analytics";
+import { highlight } from "../utils/color";
+import {
+  analyzeRegistryItemCompatibility,
+  findInstalledSnippetItemKeys,
+  getProjectSeedPackageVersionSpecs,
+  logCompatibilityReport,
+} from "../utils/compatibility";
+import { CliError, handleCliError, isCliCancelError, isVerboseMode } from "../utils/error";
+
+const compatOptionsSchema = z.object({
+  itemIds: z.array(z.string()).optional(),
+  component: z.union([z.string(), z.array(z.string())]).optional(),
+  all: z.boolean(),
+  registry: z.string().optional(),
+  cwd: z.string(),
+  baseUrl: z.string().optional(),
+});
+
+function parseTargetInputs({
+  itemIds,
+  component,
+}: {
+  itemIds?: string[];
+  component?: string | string[];
+}) {
+  const normalizeInput = (value: string) => value.trim().replace(/\s+/g, "-");
+  const itemInputs = (itemIds ?? []).map(normalizeInput).filter(Boolean);
+  const componentInputs = (Array.isArray(component) ? component : [component])
+    .filter((value): value is string => !!value)
+    .flatMap((value) => value.split(","))
+    .map(normalizeInput)
+    .filter(Boolean);
+
+  return Array.from(new Set([...itemInputs, ...componentInputs]));
+}
+
+function resolveExplicitItemKeys({
+  publicRegistries,
+  targetInputs,
+  defaultRegistry,
+}: {
+  publicRegistries: Array<{ id?: string; items?: Array<{ id?: string }> }>;
+  targetInputs: string[];
+  defaultRegistry?: string;
+}) {
+  const allItemKeys = publicRegistries
+    .filter((registry): registry is { id: string; items: Array<{ id: string }> } => {
+      return typeof registry.id === "string" && Array.isArray(registry.items);
+    })
+    .flatMap((registry) =>
+      registry.items
+        .filter((item): item is { id: string } => typeof item.id === "string")
+        .map((item) => `${registry.id}:${item.id}`),
+    );
+  const result = new Set<string>();
+
+  for (const input of targetInputs) {
+    const itemKey = input.includes(":")
+      ? input
+      : defaultRegistry
+        ? `${defaultRegistry}:${input}`
+        : (() => {
+            const matchedItemKeys = allItemKeys.filter((itemKey) => itemKey.endsWith(`:${input}`));
+            if (!matchedItemKeys.length) {
+              throw new CliError({
+                message: `${highlight(input)}: 항목을 찾을 수 없어요.`,
+                hint: `${highlight("ui:action-button")}처럼 registry를 포함해서 입력해보세요.`,
+              });
+            }
+
+            if (matchedItemKeys.length > 1) {
+              throw new CliError({
+                message: `${highlight(input)}: 같은 이름의 항목이 여러 레지스트리에 있어요.`,
+                details: matchedItemKeys.map((itemKey) => `- ${itemKey}`),
+                hint: `${highlight("ui:action-button")}처럼 registry를 포함해서 입력해보세요.`,
+              });
+            }
+
+            return matchedItemKeys[0];
+          })();
+
+    if (!allItemKeys.includes(itemKey)) {
+      throw new CliError({
+        message: `${highlight(itemKey)}: 항목을 찾을 수 없어요.`,
+      });
+    }
+
+    result.add(itemKey);
+  }
+
+  return Array.from(result);
+}
+
+export const compatCommand = (cli: CAC) => {
+  cli
+    .command("compat [...item-ids]", "check snippet compatibility")
+    .option("-c, --component <component>", "검사할 컴포넌트. 여러 번 또는 쉼표로 지정 가능")
+    .option("-a, --all", "모든 registry 항목을 검사", {
+      default: false,
+    })
+    .option("-r, --registry <registryId>", "컴포넌트 shorthand 입력 시 기본 registry")
+    .option("--cwd <cwd>", "the working directory. defaults to the current directory.", {
+      default: process.cwd(),
+    })
+    .option(
+      "-u, --baseUrl <baseUrl>",
+      "the base url of the registry. defaults to the current directory.",
+      { default: BASE_URL },
+    )
+    .example("seed-design compat")
+    .example("seed-design compat -c action-button")
+    .example("seed-design compat ui:action-button ui:alert-dialog")
+    .example("seed-design compat --all")
+    .action(async (itemIds, opts) => {
+      const startTime = Date.now();
+      const verbose = isVerboseMode(opts);
+      p.intro("seed-design compat");
+
+      try {
+        const parsed = compatOptionsSchema.safeParse({ itemIds, ...opts });
+        if (!parsed.success) {
+          throw parsed.error;
+        }
+
+        const { data: options } = parsed;
+        const { start, stop } = p.spinner();
+
+        start("Registry를 가져오고 있어요...");
+        const publicRegistries = await (async () => {
+          try {
+            const registries = await Promise.all(
+              (await fetchAvailableRegistries({ baseUrl: options.baseUrl })).map(async ({ id }) =>
+                fetchRegistry({ baseUrl: options.baseUrl, registryId: id }),
+              ),
+            );
+            stop("Registry를 가져왔어요.");
+            return registries;
+          } catch (error) {
+            stop("Registry를 가져오지 못했어요.");
+            throw error;
+          }
+        })();
+
+        const targetInputs = parseTargetInputs({
+          itemIds: options.itemIds,
+          component: options.component,
+        });
+
+        const targetItemKeys = (() => {
+          if (options.all) {
+            return publicRegistries.flatMap((registry) =>
+              registry.items.map((item) => `${registry.id}:${item.id}`),
+            );
+          }
+
+          if (targetInputs.length > 0) {
+            return resolveExplicitItemKeys({
+              publicRegistries,
+              targetInputs,
+              defaultRegistry: options.registry,
+            });
+          }
+
+          const rawConfigPromise = getRawConfig(options.cwd);
+          return rawConfigPromise;
+        })();
+
+        const resolvedTargetItemKeys = Array.isArray(targetItemKeys)
+          ? targetItemKeys
+          : await (async () => {
+              const rawConfig = await targetItemKeys;
+              if (!rawConfig) {
+                throw new CliError({
+                  message: "seed-design.json 파일이 없어 설치된 스니펫 경로를 알 수 없어요.",
+                  hint: "`seed-design init`으로 설정을 만든 뒤 실행하거나, `--all`/`-c`로 검사 대상을 직접 지정해주세요.",
+                });
+              }
+
+              const rootPath = path.resolve(options.cwd, rawConfig.path);
+              const installedItemKeys = findInstalledSnippetItemKeys({
+                publicRegistries,
+                rootPath,
+              });
+
+              if (!installedItemKeys.length) {
+                p.log.info(
+                  `${highlight(path.relative(options.cwd, rootPath) || rawConfig.path)}에서 설치된 스니펫을 찾지 못했어요.`,
+                );
+                return [];
+              }
+
+              return installedItemKeys;
+            })();
+
+        if (!resolvedTargetItemKeys.length) {
+          p.outro("검사할 스니펫이 없어요.");
+          process.exit(0);
+        }
+
+        const projectPackageVersions = getProjectSeedPackageVersionSpecs(options.cwd);
+        const compatibilityReport = analyzeRegistryItemCompatibility({
+          publicRegistries,
+          itemKeys: resolvedTargetItemKeys,
+          projectPackageVersions,
+        });
+
+        p.log.info(`검사 대상: ${highlight(compatibilityReport.checkedItemKeys.join(", "))}`);
+
+        if (!compatibilityReport.issues.length) {
+          p.outro("모든 스니펫이 현재 @seed-design/react, @seed-design/css와 호환돼요.");
+
+          try {
+            await analytics.track(options.cwd, {
+              event: "compat",
+              properties: {
+                checked_items_count: compatibilityReport.checkedItemKeys.length,
+                incompatible_items_count: 0,
+                duration_ms: Date.now() - startTime,
+              },
+            });
+          } catch (telemetryError) {
+            if (verbose) {
+              console.error("[Telemetry] compat tracking failed:", telemetryError);
+            }
+          }
+
+          process.exit(0);
+        }
+
+        logCompatibilityReport({
+          report: compatibilityReport,
+          title: "현재 프로젝트 버전과 호환되지 않는 스니펫을 찾았어요.",
+        });
+        p.log.info(
+          "필요한 버전으로 @seed-design/react 또는 @seed-design/css를 맞춘 뒤 다시 실행해보세요.",
+        );
+        p.outro("호환성 이슈가 있어요.");
+
+        try {
+          await analytics.track(options.cwd, {
+            event: "compat",
+            properties: {
+              checked_items_count: compatibilityReport.checkedItemKeys.length,
+              incompatible_items_count: new Set(
+                compatibilityReport.issues.map((issue) => issue.itemKey),
+              ).size,
+              issue_count: compatibilityReport.issues.length,
+              duration_ms: Date.now() - startTime,
+            },
+          });
+        } catch (telemetryError) {
+          if (verbose) {
+            console.error("[Telemetry] compat tracking failed:", telemetryError);
+          }
+        }
+
+        process.exit(1);
+      } catch (error) {
+        if (isCliCancelError(error)) {
+          p.outro(highlight(error.message));
+          process.exit(0);
+        }
+
+        handleCliError(error, {
+          defaultMessage: "호환성 검사에 실패했어요.",
+          defaultHint: "`--verbose` 옵션으로 상세 오류를 확인해보세요.",
+          verbose,
+        });
+        process.exit(1);
+      }
+    });
+};