@seed-design/cli 1.2.1 → 1.3.0

package/src/commands/docs.ts

@@ -0,0 +1,312 @@
+import { fetchDocsIndex } from "@/src/utils/fetch";
+import * as p from "@clack/prompts";
+import type { CAC } from "cac";
+import { z } from "zod";
+import { BASE_URL } from "../constants";
+import { analytics } from "../utils/analytics";
+import { highlight } from "../utils/color";
+import {
+  CliCancelError,
+  CliError,
+  handleCliError,
+  isCliCancelError,
+  isVerboseMode,
+} from "../utils/error";
+import type { DocsCategory, DocsItem, DocsSection } from "../schema";
+
+const GITHUB_SNIPPET_BASE =
+  "https://raw.githubusercontent.com/daangn/seed-design/refs/heads/dev/docs/registry";
+
+const docsOptionsSchema = z.object({
+  query: z.string().optional(),
+  baseUrl: z.string().optional(),
+});
+
+function buildSnippetUrl(registryId: string, snippetPath: string): string {
+  return `${GITHUB_SNIPPET_BASE}/${registryId}/${snippetPath}`;
+}
+
+function printDocsResult(item: DocsItem, baseUrl: string) {
+  const docLink = `${baseUrl}${item.docUrl}`;
+  const llmsLink = `${baseUrl}/llms${item.docUrl}.txt`;
+
+  const lines = [item.id, `- docs: ${docLink}`, `- llms.txt: ${llmsLink}`];
+
+  if (item.snippetKey && item.snippets && item.snippets.length > 0) {
+    const [registryId] = item.snippetKey.split(":");
+    if (registryId === "ui" || registryId === "breeze") {
+      if (item.snippets.length === 1) {
+        lines.push(`- snippet: ${buildSnippetUrl(registryId, item.snippets[0].path)}`);
+      } else {
+        lines.push("- snippet:");
+        for (const snippet of item.snippets) {
+          lines.push(`   - ${snippet.label}: ${buildSnippetUrl(registryId, snippet.path)}`);
+        }
+      }
+    }
+  }
+
+  p.log.message(lines.join("\n"));
+}
+
+/**
+ * Parse a path-style query into segments.
+ * e.g. "react/components/action-button" → ["react", "components", "action-button"]
+ */
+function parseQueryPath(query: string): string[] {
+  return query
+    .split("/")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Search all items across all categories/sections.
+ */
+function searchAllItems(
+  categories: DocsCategory[],
+  query: string,
+): { item: DocsItem; categoryLabel: string; sectionLabel: string }[] {
+  const q = query.toLowerCase();
+  return categories.flatMap((cat) =>
+    cat.sections.flatMap((sec) =>
+      sec.items
+        .filter((item) => item.id.toLowerCase().includes(q) || item.title.toLowerCase().includes(q))
+        .map((item) => ({
+          item,
+          categoryLabel: cat.label,
+          sectionLabel: sec.label,
+        })),
+    ),
+  );
+}
+
+async function selectItem(items: DocsItem[]): Promise<DocsItem> {
+  const selected = await p.select({
+    message: "항목을 선택해주세요",
+    options: items.map((item) => ({
+      label: `${item.deprecated ? "(deprecated) " : ""}${item.title}`,
+      value: item,
+      hint: item.description,
+    })),
+  });
+  if (p.isCancel(selected)) throw new CliCancelError();
+  return selected;
+}
+
+async function selectSection(sections: DocsSection[]): Promise<DocsSection> {
+  const selected = await p.select({
+    message: "섹션을 선택해주세요",
+    options: sections.map((sec) => ({
+      label: sec.label,
+      value: sec,
+      hint: `${sec.items.length}개 항목`,
+    })),
+  });
+  if (p.isCancel(selected)) throw new CliCancelError();
+  return selected;
+}
+
+async function selectCategory(categories: DocsCategory[]): Promise<DocsCategory> {
+  const selected = await p.select({
+    message: "카테고리를 선택해주세요",
+    options: categories.map((cat) => ({
+      label: cat.label,
+      value: cat,
+      hint: `${cat.sections.reduce((sum, s) => sum + s.items.length, 0)}개 항목`,
+    })),
+  });
+  if (p.isCancel(selected)) throw new CliCancelError();
+  return selected;
+}
+
+export const docsCommand = (cli: CAC) => {
+  cli
+    .command("docs [query]", "문서 링크, llms.txt 링크, 스니펫 링크를 조회합니다")
+    .option("-u, --baseUrl <baseUrl>", `레지스트리의 기본 URL (기본값: ${BASE_URL})`, {
+      default: BASE_URL,
+    })
+    .example("seed-design docs")
+    .example("seed-design docs action-button")
+    .example("seed-design docs react")
+    .example("seed-design docs react/components")
+    .example("seed-design docs react/components/action-button")
+    .action(async (query, opts) => {
+      const startTime = Date.now();
+      const verbose = isVerboseMode(opts);
+      p.intro("seed-design docs");
+
+      try {
+        const parsed = docsOptionsSchema.safeParse({ query, ...opts });
+        if (!parsed.success) {
+          throw parsed.error;
+        }
+
+        const { data: options } = parsed;
+        const baseUrl = options.baseUrl ?? BASE_URL;
+
+        const { start, stop } = p.spinner();
+        start("문서 목록을 가져오고 있어요...");
+
+        const docsIndex = await (async () => {
+          try {
+            const index = await fetchDocsIndex({ baseUrl });
+            stop("문서 목록을 가져왔어요.");
+            return index;
+          } catch (error) {
+            stop("문서 목록을 가져오지 못했어요.");
+            throw error;
+          }
+        })();
+
+        const { categories } = docsIndex;
+        let selectedItem: DocsItem;
+
+        if (options.query) {
+          const segments = parseQueryPath(options.query);
+
+          // Try to resolve as path: category / section / item
+          const matchedCategory = categories.find((c) => c.id === segments[0]);
+
+          if (matchedCategory && segments.length >= 2) {
+            const matchedSection = matchedCategory.sections.find((s) => s.id === segments[1]);
+
+            if (matchedSection && segments.length >= 3) {
+              // Full path: category/section/item
+              const matchedItem = matchedSection.items.find((i) => i.id === segments[2]);
+              if (matchedItem) {
+                selectedItem = matchedItem;
+              } else {
+                // Item not found in section — search within the section
+                const q = segments[2].toLowerCase();
+                const matched = matchedSection.items.filter(
+                  (i) => i.id.toLowerCase().includes(q) || i.title.toLowerCase().includes(q),
+                );
+                if (matched.length === 0) {
+                  throw new CliError({
+                    message: `${highlight(options.query)}: 문서를 찾을 수 없어요.`,
+                    hint: `\`seed-design docs ${matchedCategory.id}/${matchedSection.id}\`로 목록을 확인해보세요.`,
+                  });
+                }
+                if (matched.length === 1) {
+                  selectedItem = matched[0];
+                } else {
+                  selectedItem = await selectItem(matched);
+                }
+              }
+            } else if (matchedSection) {
+              // category/section — select item within section
+              selectedItem = await selectItem(matchedSection.items);
+            } else {
+              // category/??? — search within category
+              const q = segments[1].toLowerCase();
+              const matched = matchedCategory.sections.flatMap((s) =>
+                s.items
+                  .filter(
+                    (i) => i.id.toLowerCase().includes(q) || i.title.toLowerCase().includes(q),
+                  )
+                  .map((item) => ({ item, sectionLabel: s.label })),
+              );
+
+              if (matched.length === 0) {
+                throw new CliError({
+                  message: `${highlight(options.query)}: 문서를 찾을 수 없어요.`,
+                  hint: `\`seed-design docs ${matchedCategory.id}\`로 목록을 확인해보세요.`,
+                });
+              }
+              if (matched.length === 1) {
+                selectedItem = matched[0].item;
+              } else {
+                const selected = await p.select({
+                  message: `${highlight(segments[1])}에 해당하는 항목을 선택해주세요`,
+                  options: matched.map(({ item, sectionLabel }) => ({
+                    label: `[${sectionLabel}] ${item.title}`,
+                    value: item,
+                    hint: item.description,
+                  })),
+                });
+                if (p.isCancel(selected)) throw new CliCancelError();
+                selectedItem = selected;
+              }
+            }
+          } else if (matchedCategory) {
+            // Single segment matching a category — drill into it
+            if (matchedCategory.sections.length === 1) {
+              selectedItem = await selectItem(matchedCategory.sections[0].items);
+            } else {
+              const section = await selectSection(matchedCategory.sections);
+              selectedItem = await selectItem(section.items);
+            }
+          } else {
+            // No category match — global search
+            const matched = searchAllItems(categories, options.query);
+
+            if (matched.length === 0) {
+              throw new CliError({
+                message: `${highlight(options.query)}: 문서를 찾을 수 없어요.`,
+                hint: "`seed-design docs`로 전체 목록을 확인해보세요.",
+              });
+            }
+            if (matched.length === 1) {
+              selectedItem = matched[0].item;
+            } else {
+              const selected = await p.select({
+                message: `${highlight(options.query)}에 해당하는 항목을 선택해주세요`,
+                options: matched.map(({ item, categoryLabel, sectionLabel }) => ({
+                  label: `[${categoryLabel} > ${sectionLabel}] ${item.title}`,
+                  value: item,
+                  hint: item.description,
+                })),
+              });
+              if (p.isCancel(selected)) throw new CliCancelError();
+              selectedItem = selected;
+            }
+          }
+        } else {
+          // Full interactive flow: category → section → item
+          const category = await selectCategory(categories);
+
+          let section: DocsSection;
+          if (category.sections.length === 1) {
+            section = category.sections[0];
+          } else {
+            section = await selectSection(category.sections);
+          }
+
+          selectedItem = await selectItem(section.items);
+        }
+
+        printDocsResult(selectedItem, baseUrl);
+        p.outro("완료했어요.");
+
+        const duration = Date.now() - startTime;
+        try {
+          await analytics.track(process.cwd(), {
+            event: "docs",
+            properties: {
+              query: options.query ?? null,
+              item_id: selectedItem.id,
+              has_snippet: !!(selectedItem.snippets && selectedItem.snippets.length > 0),
+              duration_ms: duration,
+            },
+          });
+        } catch (telemetryError) {
+          if (verbose) {
+            console.error("[Telemetry] docs tracking failed:", telemetryError);
+          }
+        }
+      } catch (error) {
+        if (isCliCancelError(error)) {
+          p.outro(highlight(error.message));
+          process.exit(0);
+        }
+
+        handleCliError(error, {
+          defaultMessage: "문서 조회에 실패했어요.",
+          defaultHint: "`--verbose` 옵션으로 상세 오류를 확인해보세요.",
+          verbose,
+        });
+        process.exit(1);
+      }
+    });
+};

package/src/commands/init.ts

@@ -1,9 +1,9 @@
 import * as p from "@clack/prompts";
-import fs from "fs-extra";
-import path from "path";
 import { z } from "zod";
 import { analytics } from "../utils/analytics";
 import { highlight } from "../utils/color";
+import { handleCliError, isCliCancelError, isVerboseMode } from "../utils/error";
+import { DEFAULT_INIT_CONFIG, promptInitConfig, writeInitConfigFile } from "../utils/init-config";
 
 import type { Config } from "@/src/utils/get-config";
 
@@ -13,6 +13,7 @@ import dedent from "dedent";
 const initOptionsSchema = z.object({
   cwd: z.string(),
   yes: z.boolean().optional(),
+  default: z.boolean().optional(),
 });
 
 export const initCommand = (cli: CAC) => {
@@ -22,64 +23,38 @@ export const initCommand = (cli: CAC) => {
       default: process.cwd(),
     })
     .option("-y, --yes", "모든 질문에 대해 기본값으로 답변합니다.")
+    .option("--default", "Deprecated. --yes와 동일하게 기본값으로 생성합니다.")
     .action(async (opts) => {
       const startTime = Date.now();
+      const verbose = isVerboseMode(opts);
       p.intro("seed-design.json 파일 생성");
 
-      const options = initOptionsSchema.parse(opts);
-      const isYesOption = options.yes;
-      let config: Config = {
-        rsc: false,
-        tsx: true,
-        path: "./seed-design",
-        telemetry: true,
-      };
-
-      if (!isYesOption) {
-        const group = await p.group(
-          {
-            tsx: () =>
-              p.confirm({
-                message: `${highlight("TypeScript")}를 사용중이신가요?`,
-                initialValue: true,
-              }),
-            rsc: () =>
-              p.confirm({
-                message: `${highlight("React Server Components")}를 사용중이신가요?`,
-                initialValue: false,
-              }),
-            path: () =>
-              p.text({
-                message: `${highlight("seed-design 폴더")} 경로를 입력해주세요. (기본값은 프로젝트 루트에 생성됩니다.)`,
-                initialValue: "./seed-design",
-                defaultValue: "./seed-design",
-                placeholder: "./seed-design",
-              }),
-            telemetry: () =>
-              p.confirm({
-                message: `개선을 위해 ${highlight("익명 사용 데이터")}를 수집할까요?`,
-                initialValue: true,
-              }),
-          },
-          {
-            onCancel: () => {
-              p.cancel("작업이 취소됐어요.");
-              process.exit(0);
-            },
-          },
-        );
+      try {
+        const parsed = initOptionsSchema.safeParse(opts);
+        if (!parsed.success) {
+          throw parsed.error;
+        }
 
-        config = {
-          ...group,
-        };
-      }
+        const options = parsed.data;
+        const isDefaultMode = options.yes || options.default;
+        const config: Config = isDefaultMode ? DEFAULT_INIT_CONFIG : await promptInitConfig();
 
-      try {
         const { start, stop } = p.spinner();
         start("seed-design.json 파일 생성중...");
-        const targetPath = path.resolve(options.cwd, "seed-design.json");
-        await fs.writeFile(targetPath, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
-        const relativePath = path.relative(process.cwd(), targetPath);
+        const relativePath = await (async () => {
+          try {
+            const result = await writeInitConfigFile({
+              cwd: options.cwd,
+              config,
+            });
+
+            return result.relativePath;
+          } catch (error) {
+            stop("seed-design.json 파일 생성이 중단됐어요.");
+            throw error;
+          }
+        })();
+
         stop(`seed-design.json 파일이 ${highlight(relativePath)}에 생성됐어요.`);
 
         p.log.info(highlight("seed-design add {component} 명령어로 컴포넌트를 추가해보세요!"));
@@ -99,23 +74,37 @@ export const initCommand = (cli: CAC) => {
         );
 
         p.outro("작업이 완료됐어요.");
+
+        // init 성공 이벤트 추적
+        const duration = Date.now() - startTime;
+        try {
+          await analytics.track(options.cwd, {
+            event: "init",
+            properties: {
+              tsx: config.tsx,
+              rsc: config.rsc,
+              telemetry: config.telemetry,
+              yes_option: isDefaultMode,
+              duration_ms: duration,
+            },
+          });
+        } catch (telemetryError) {
+          if (verbose) {
+            console.error("[Telemetry] init tracking failed:", telemetryError);
+          }
+        }
       } catch (error) {
-        p.log.error(`seed-design.json 파일 생성에 실패했어요. ${error}`);
-        p.outro(highlight("작업이 취소됐어요."));
+        if (isCliCancelError(error)) {
+          p.outro(highlight(error.message));
+          process.exit(0);
+        }
+
+        handleCliError(error, {
+          defaultMessage: "seed-design.json 파일 생성에 실패했어요.",
+          defaultHint: "`--verbose` 옵션으로 상세 오류를 확인해보세요.",
+          verbose,
+        });
         process.exit(1);
       }
-
-      // init 성공 이벤트 추적
-      const duration = Date.now() - startTime;
-      await analytics.track(options.cwd, {
-        event: "init",
-        properties: {
-          tsx: config.tsx,
-          rsc: config.rsc,
-          telemetry: config.telemetry,
-          yes_option: isYesOption,
-          duration_ms: duration,
-        },
-      });
     });
 };

package/src/index.ts

@@ -2,6 +2,8 @@
 
 import { addCommand } from "@/src/commands/add";
 import { addAllCommand } from "@/src/commands/add-all";
+import { compatCommand } from "@/src/commands/compat";
+import { docsCommand } from "@/src/commands/docs";
 import { initCommand } from "@/src/commands/init";
 import { getPackageInfo } from "@/src/utils/get-package-info";
 import { cac } from "cac";
@@ -12,9 +14,13 @@ const CLI = cac(NAME);
 async function main() {
   const packageInfo = getPackageInfo();
 
+  CLI.option("--verbose", "오류 상세 정보를 출력합니다.");
+
   /* Commands */
   addCommand(CLI);
   addAllCommand(CLI);
+  compatCommand(CLI);
+  docsCommand(CLI);
   initCommand(CLI);
 
   CLI.version(packageInfo.version || "1.0.0", "-v, --version");

package/src/schema.ts

@@ -27,7 +27,13 @@ export const publicRegistryItemSchema = z.object({
 
   ///////////////////////////////////////////////////////////////
 
-  snippets: z.array(z.object({ path: z.string(), content: z.string() })),
+  snippets: z.array(
+    z.object({
+      path: z.string(),
+      dependencies: z.record(z.string(), z.string()).optional(),
+      content: z.string(),
+    }),
+  ),
 });
 
 /**
@@ -39,9 +45,14 @@ export const publicRegistrySchema = z.object({
   hideFromCLICatalog: z.boolean().optional(),
 
   items: z.array(
-    publicRegistryItemSchema
-      .omit({ snippets: true })
-      .extend({ snippets: z.array(z.object({ path: z.string() })) }),
+    publicRegistryItemSchema.omit({ snippets: true }).extend({
+      snippets: z.array(
+        z.object({
+          path: z.string(),
+          dependencies: z.record(z.string(), z.string()).optional(),
+        }),
+      ),
+    }),
   ),
 });
 
@@ -53,3 +64,41 @@ export const publicAvailableRegistriesSchema = z.array(z.object({ id: z.string()
 export type PublicRegistryItem = z.infer<typeof publicRegistryItemSchema>;
 export type PublicRegistry = z.infer<typeof publicRegistrySchema>;
 export type PublicAvailableRegistries = z.infer<typeof publicAvailableRegistriesSchema>;
+
+///////////////////////////////////////////////////////////////
+
+export const docsSnippetSchema = z.object({
+  label: z.string(),
+  path: z.string(),
+});
+
+export const docsItemSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  description: z.string().optional(),
+  docUrl: z.string(),
+  deprecated: z.boolean().optional(),
+  snippetKey: z.string().optional(),
+  snippets: z.array(docsSnippetSchema).optional(),
+});
+
+export const docsSectionSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  items: z.array(docsItemSchema),
+});
+
+export const docsCategorySchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  sections: z.array(docsSectionSchema),
+});
+
+export const docsIndexSchema = z.object({
+  categories: z.array(docsCategorySchema),
+});
+
+export type DocsItem = z.infer<typeof docsItemSchema>;
+export type DocsSection = z.infer<typeof docsSectionSchema>;
+export type DocsCategory = z.infer<typeof docsCategorySchema>;
+export type DocsIndex = z.infer<typeof docsIndexSchema>;