@seed-design/cli 1.2.2 → 1.3.1

package/src/commands/upgrade.ts

@@ -0,0 +1,387 @@
+import { getPackageInfo } from "@/src/utils/get-package-info";
+import * as p from "@clack/prompts";
+import { coerce, valid } from "semver";
+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 {
+  CliCancelError,
+  CliError,
+  handleCliError,
+  isCliCancelError,
+  isVerboseMode,
+} from "../utils/error";
+import { fetchChangelog, fetchLatestVersion } from "../utils/fetch";
+
+const SEED_SCOPE = "@seed-design/";
+
+const upgradeOptionsSchema = z.object({
+  packageName: z.string().optional(),
+  cwd: z.string(),
+  baseUrl: z.string(),
+  raw: z.boolean(),
+  all: z.boolean(),
+});
+
+function toFullPackageName(input: string): string {
+  return input.startsWith(SEED_SCOPE) ? input : `${SEED_SCOPE}${input}`;
+}
+
+function toSlug(packageName: string): string {
+  return packageName.replace(SEED_SCOPE, "");
+}
+
+function findInstalledSeedPackages(cwd: string): Record<string, string> {
+  const packageInfo = getPackageInfo(cwd);
+  const allDeps = {
+    ...packageInfo.dependencies,
+    ...packageInfo.devDependencies,
+    ...packageInfo.peerDependencies,
+    ...packageInfo.optionalDependencies,
+  };
+
+  const seedPackages: Record<string, string> = {};
+  for (const [name, version] of Object.entries(allDeps)) {
+    if (name.startsWith(SEED_SCOPE) && version) {
+      seedPackages[name] = version;
+    }
+  }
+
+  return seedPackages;
+}
+
+function resolveExactVersion(versionSpec: string): string | null {
+  let normalized = versionSpec.trim();
+
+  if (normalized.startsWith("workspace:")) {
+    normalized = normalized.slice("workspace:".length).trim();
+  }
+
+  if (normalized.startsWith("npm:")) {
+    const lastAt = normalized.lastIndexOf("@");
+    if (lastAt > 4) {
+      normalized = normalized.slice(lastAt + 1);
+    }
+  }
+
+  if (valid(normalized)) return normalized;
+
+  const coerced = coerce(normalized);
+  if (coerced) return coerced.version;
+
+  return null;
+}
+
+interface UpgradeOneResult {
+  package: string;
+  currentVersion: string;
+  latestVersion: string;
+  upToDate: boolean;
+  changelog: string | null;
+}
+
+async function upgradeOne({
+  targetPackage,
+  currentVersionSpec,
+  baseUrl,
+}: {
+  targetPackage: string;
+  currentVersionSpec: string;
+  baseUrl: string;
+}): Promise<UpgradeOneResult> {
+  const currentVersion = resolveExactVersion(currentVersionSpec);
+
+  if (!currentVersion) {
+    throw new CliError({
+      message: `${targetPackage}의 버전을 파싱할 수 없어요: ${currentVersionSpec}`,
+      hint: "package.json에서 버전 형식을 확인해주세요.",
+    });
+  }
+
+  const latestVersion = await fetchLatestVersion(targetPackage);
+
+  if (currentVersion === latestVersion) {
+    return {
+      package: targetPackage,
+      currentVersion,
+      latestVersion,
+      upToDate: true,
+      changelog: null,
+    };
+  }
+
+  const slug = toSlug(targetPackage);
+  const changelog = await fetchChangelog({
+    baseUrl,
+    packageSlug: slug,
+    version: currentVersion,
+  });
+
+  return {
+    package: targetPackage,
+    currentVersion,
+    latestVersion,
+    upToDate: false,
+    changelog,
+  };
+}
+
+function printResultRaw(result: UpgradeOneResult & { error?: string }) {
+  if (result.error) {
+    console.error(`## ${result.package}\n\nError: ${result.error}\n`);
+  } else if (result.upToDate) {
+    console.log(`${result.package}@${result.currentVersion} is already up to date.\n`);
+  } else {
+    console.log(result.changelog);
+    console.log("");
+  }
+}
+
+function printResultInteractive(result: UpgradeOneResult & { error?: string }) {
+  if (result.error) {
+    p.log.error(`${highlight(result.package)}: ${result.error}`);
+  } else if (result.upToDate) {
+    p.log.info(
+      `${highlight(result.package)}: ${highlight(result.currentVersion)} — 이미 최신 버전이에요.`,
+    );
+  } else {
+    p.log.info(
+      `${highlight(result.package)}: ${highlight(result.currentVersion)} → ${highlight(result.latestVersion)}`,
+    );
+    p.log.message(result.changelog ?? "");
+    p.log.info(
+      `업그레이드하려면: ${highlight(`bun add ${result.package}@${result.latestVersion}`)}`,
+    );
+  }
+}
+
+async function trackResults(cwd: string, results: UpgradeOneResult[], startTime: number) {
+  try {
+    for (const result of results) {
+      await analytics.track(cwd, {
+        event: "upgrade",
+        properties: {
+          package: result.package,
+          current_version: result.currentVersion,
+          latest_version: result.latestVersion,
+          up_to_date: result.upToDate,
+          duration_ms: Date.now() - startTime,
+        },
+      });
+    }
+  } catch {}
+}
+
+export const upgradeCommand = (cli: CAC) => {
+  cli
+    .command(
+      "upgrade [package-name]",
+      "패키지의 현재 버전과 최신 버전 사이의 변경사항을 확인합니다",
+    )
+    .option("-c, --cwd <cwd>", "작업 디렉토리. 기본값은 현재 디렉토리입니다.", {
+      default: process.cwd(),
+    })
+    .option("-u, --baseUrl <baseUrl>", "changelog를 조회할 base URL입니다.", { default: BASE_URL })
+    .option("--raw", "UI 없이 순수 마크다운만 출력합니다. LLM 파이프에 유용합니다.", {
+      default: false,
+    })
+    .option("-a, --all", "설치된 모든 @seed-design 패키지의 변경사항을 확인합니다.", {
+      default: false,
+    })
+    .example("seed-design upgrade")
+    .example("seed-design upgrade react")
+    .example("seed-design upgrade --all")
+    .example("seed-design upgrade --all --raw")
+    .action(async (packageName, opts) => {
+      const startTime = Date.now();
+      const verbose = isVerboseMode(opts);
+      const parsed = upgradeOptionsSchema.safeParse({ packageName, ...opts });
+      if (!parsed.success) {
+        if (opts.raw) {
+          console.error(parsed.error.message);
+          process.exit(1);
+        }
+        p.intro("seed-design upgrade");
+        handleCliError(parsed.error, {
+          defaultMessage: "업그레이드 확인에 실패했어요.",
+          defaultHint: "`--verbose` 옵션으로 상세 오류를 확인해보세요.",
+          verbose,
+        });
+        process.exit(1);
+      }
+
+      const { data: options } = parsed;
+      const { raw, all } = options;
+
+      if (!raw) p.intro("seed-design upgrade");
+
+      try {
+        const seedPackages = findInstalledSeedPackages(options.cwd);
+        const packageNames = Object.keys(seedPackages);
+
+        if (packageNames.length === 0) {
+          throw new CliError({
+            message: "프로젝트에 설치된 @seed-design 패키지를 찾을 수 없어요.",
+            hint: "`bun add @seed-design/react`로 패키지를 설치해보세요.",
+          });
+        }
+
+        if (options.packageName && all) {
+          throw new CliError({
+            message: "패키지명과 --all 옵션을 동시에 사용할 수 없어요.",
+            hint: "`seed-design upgrade --all` 또는 `seed-design upgrade react` 중 하나만 사용해주세요.",
+          });
+        }
+
+        // --all: iterate all packages
+        if (all) {
+          if (raw) {
+            const results = await Promise.all(
+              packageNames.map((name) =>
+                upgradeOne({
+                  targetPackage: name,
+                  currentVersionSpec: seedPackages[name],
+                  baseUrl: options.baseUrl,
+                }).catch((error): UpgradeOneResult & { error: string } => ({
+                  package: name,
+                  currentVersion: seedPackages[name],
+                  latestVersion: "unknown",
+                  upToDate: false,
+                  changelog: null,
+                  error: error instanceof Error ? error.message : String(error),
+                })),
+              ),
+            );
+
+            for (const result of results) {
+              printResultRaw(result);
+            }
+
+            await trackResults(options.cwd, results, startTime);
+            const hasErrors = results.some((r) => "error" in r && Boolean(r.error));
+            process.exit(hasErrors ? 1 : 0);
+          }
+
+          // --all interactive
+          const { start, stop } = p.spinner();
+          start("모든 패키지의 변경사항을 가져오고 있어요...");
+          const results = await Promise.all(
+            packageNames.map((name) =>
+              upgradeOne({
+                targetPackage: name,
+                currentVersionSpec: seedPackages[name],
+                baseUrl: options.baseUrl,
+              }).catch((error): UpgradeOneResult & { error: string } => ({
+                package: name,
+                currentVersion: seedPackages[name],
+                latestVersion: "unknown",
+                upToDate: false,
+                changelog: null,
+                error: error instanceof Error ? error.message : String(error),
+              })),
+            ),
+          );
+          stop("변경사항을 가져왔어요.");
+
+          for (const result of results) {
+            printResultInteractive(result);
+          }
+
+          p.outro("완료했어요.");
+          await trackResults(options.cwd, results, startTime);
+          const hasErrors = results.some((r) => "error" in r && Boolean(r.error));
+          process.exit(hasErrors ? 1 : 0);
+        }
+
+        // resolve target package
+        let targetPackage: string;
+
+        if (options.packageName) {
+          targetPackage = toFullPackageName(options.packageName);
+
+          if (!seedPackages[targetPackage]) {
+            throw new CliError({
+              message: `${highlight(targetPackage)}: 프로젝트에 설치되어 있지 않아요.`,
+              hint: `설치된 패키지: ${packageNames.map((n) => highlight(n)).join(", ")}`,
+            });
+          }
+        } else {
+          // no package, no --all: interactive select
+          if (raw) {
+            throw new CliError({
+              message: "--raw 모드에서는 패키지명 또는 --all 옵션이 필요해요.",
+              hint: "예: `seed-design upgrade react --raw` 또는 `seed-design upgrade --all --raw`",
+            });
+          }
+
+          if (packageNames.length === 1) {
+            targetPackage = packageNames[0];
+          } else {
+            const selected = await p.select({
+              message: "변경사항을 확인할 패키지를 선택해주세요",
+              options: packageNames.map((name) => ({
+                label: name,
+                value: name,
+                hint: seedPackages[name],
+              })),
+            });
+            if (p.isCancel(selected)) throw new CliCancelError();
+            targetPackage = selected;
+          }
+        }
+
+        // single package
+        if (raw) {
+          const result = await upgradeOne({
+            targetPackage,
+            currentVersionSpec: seedPackages[targetPackage],
+            baseUrl: options.baseUrl,
+          });
+          printResultRaw(result);
+          await trackResults(options.cwd, [result], startTime);
+          process.exit(0);
+        }
+
+        // single package interactive
+        const { start, stop } = p.spinner();
+        start("최신 버전을 확인하고 있어요...");
+        let result: UpgradeOneResult;
+        try {
+          result = await upgradeOne({
+            targetPackage,
+            currentVersionSpec: seedPackages[targetPackage],
+            baseUrl: options.baseUrl,
+          });
+          stop("변경사항을 가져왔어요.");
+        } catch (error) {
+          stop("변경사항을 가져오지 못했어요.");
+          throw error;
+        }
+
+        printResultInteractive(result);
+        p.outro("완료했어요.");
+        await trackResults(options.cwd, [result], startTime);
+      } catch (error) {
+        if (isCliCancelError(error)) {
+          if (!raw) p.outro(highlight(error.message));
+          process.exit(0);
+        }
+
+        if (raw) {
+          const msg = error instanceof Error ? error.message : String(error);
+          console.error(msg);
+          process.exit(1);
+        }
+
+        handleCliError(error, {
+          defaultMessage: "업그레이드 확인에 실패했어요.",
+          defaultHint: "`--verbose` 옵션으로 상세 오류를 확인해보세요.",
+          verbose,
+        });
+        process.exit(1);
+      }
+    });
+};

package/src/index.ts

@@ -3,7 +3,9 @@
 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 { upgradeCommand } from "@/src/commands/upgrade";
 import { getPackageInfo } from "@/src/utils/get-package-info";
 import { cac } from "cac";
 
@@ -19,7 +21,9 @@ async function main() {
   addCommand(CLI);
   addAllCommand(CLI);
   compatCommand(CLI);
+  docsCommand(CLI);
   initCommand(CLI);
+  upgradeCommand(CLI);
 
   CLI.version(packageInfo.version || "1.0.0", "-v, --version");
   CLI.help();

package/src/schema.ts

@@ -45,16 +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(),
-            dependencies: z.record(z.string(), z.string()).optional(),
-          }),
-        ),
-      }),
+    publicRegistryItemSchema.omit({ snippets: true }).extend({
+      snippets: z.array(
+        z.object({
+          path: z.string(),
+          dependencies: z.record(z.string(), z.string()).optional(),
+        }),
+      ),
+    }),
   ),
 });
 
@@ -66,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>;

package/src/tests/resolve-dependencies.test.ts

@@ -3,7 +3,7 @@ import { resolveDependencies } from "../utils/resolve-dependencies";
 import type { PublicRegistry } from "@/src/schema";
 
 describe("resolveDependencies", () => {
-  it("should resolve a simple item without dependencies", () => {
+  it("의존성이 없는 단일 아이템을 해석해야 한다", () => {
     const publicRegistries: PublicRegistry[] = [
       {
         id: "ui",
@@ -36,7 +36,7 @@ describe("resolveDependencies", () => {
     expect(result.npmDependenciesToAdd.size).toBe(0);
   });
 
-  it("should resolve npm dependencies", () => {
+  it("npm 의존성을 수집해야 한다", () => {
     const publicRegistries: PublicRegistry[] = [
       {
         id: "ui",
@@ -61,7 +61,7 @@ describe("resolveDependencies", () => {
     expect(result.npmDependenciesToAdd.has("clsx")).toBe(true);
   });
 
-  it("should resolve inner dependencies recursively", () => {
+  it("innerDependencies를 재귀적으로 해석해야 한다", () => {
     const publicRegistries: PublicRegistry[] = [
       {
         id: "ui",
@@ -131,7 +131,7 @@ describe("resolveDependencies", () => {
     expect(result.npmDependenciesToAdd.has("framer-motion")).toBe(true);
   });
 
-  it("should handle multiple selected items", () => {
+  it("여러 선택 아이템을 함께 처리해야 한다", () => {
     const publicRegistries: PublicRegistry[] = [
       {
         id: "ui",
@@ -161,7 +161,7 @@ describe("resolveDependencies", () => {
     expect(result.registryItemsToAdd[0].items.map((i) => i.id)).toEqual(["button", "chip"]);
   });
 
-  it("should prevent duplicate items", () => {
+  it("중복 아이템을 제거해야 한다", () => {
     const publicRegistries: PublicRegistry[] = [
       {
         id: "ui",
@@ -186,7 +186,7 @@ describe("resolveDependencies", () => {
       },
     ];
 
-    // Select both dialog and button, but button is already a dependency of dialog
+    // dialog와 button을 동시에 선택해도 button은 dialog 의존성으로 이미 포함된다.
     const result = resolveDependencies({
       selectedItemKeys: ["ui:dialog", "ui:button"],
       publicRegistries,
@@ -194,12 +194,12 @@ describe("resolveDependencies", () => {
 
     expect(result.registryItemsToAdd).toHaveLength(1);
     expect(result.registryItemsToAdd[0].items).toHaveLength(2);
-    // Button should appear only once
+    // button은 한 번만 포함되어야 한다.
     const buttonCount = result.registryItemsToAdd[0].items.filter((i) => i.id === "button").length;
     expect(buttonCount).toBe(1);
   });
 
-  it("should handle nested inner dependencies", () => {
+  it("중첩된 innerDependencies를 처리해야 한다", () => {
     const publicRegistries: PublicRegistry[] = [
       {
         id: "ui",
@@ -268,7 +268,7 @@ describe("resolveDependencies", () => {
     expect(result.npmDependenciesToAdd.has("lodash")).toBe(true);
   });
 
-  it("should throw error for invalid snippet format", () => {
+  it("잘못된 스니펫 포맷이면 에러를 던져야 한다", () => {
     const publicRegistries: PublicRegistry[] = [];
 
     expect(() =>
@@ -279,7 +279,7 @@ describe("resolveDependencies", () => {
     ).toThrowError('Invalid snippet format: "invalid-format"');
   });
 
-  it("should throw error for non-existent snippet", () => {
+  it("존재하지 않는 스니펫이면 에러를 던져야 한다", () => {
     const publicRegistries: PublicRegistry[] = [
       {
         id: "ui",
@@ -295,7 +295,7 @@ describe("resolveDependencies", () => {
     ).toThrowError('Cannot find snippet: "ui:non-existent"');
   });
 
-  it("should throw error for missing inner dependency", () => {
+  it("inner dependency가 누락되면 에러를 던져야 한다", () => {
     const publicRegistries: PublicRegistry[] = [
       {
         id: "ui",
@@ -327,7 +327,7 @@ describe("resolveDependencies", () => {
     ).toThrowError("Cannot find dependency item: breeze:missing");
   });
 
-  it("should handle multiple registries with multiple items", () => {
+  it("여러 레지스트리와 아이템을 함께 처리해야 한다", () => {
     const publicRegistries: PublicRegistry[] = [
       {
         id: "ui",
@@ -378,7 +378,7 @@ describe("resolveDependencies", () => {
     expect(result.npmDependenciesToAdd.has("framer-motion")).toBe(true);
   });
 
-  it("should collect all npm dependencies from nested dependencies", () => {
+  it("중첩 의존성의 npm 패키지를 모두 수집해야 한다", () => {
     const publicRegistries: PublicRegistry[] = [
       {
         id: "ui",

package/src/utils/analytics.ts

@@ -60,9 +60,8 @@ async function track(cwd: string, { event, properties = {} }: TrackOptions): Pro
 
   const fullEvent = `${EVENT_PREFIX}.${event}`;
 
-  // Dev 모드: 콘솔에만 출력
+  // Dev 모드: 텔레메트리 전송 생략
   if (process.env.NODE_ENV === "dev") {
-    console.log(`📊 [Telemetry] ${fullEvent}`, properties);
     return;
   }
 

package/src/utils/fetch.ts

@@ -7,7 +7,49 @@ import {
   publicRegistryItemSchema,
   type PublicAvailableRegistries,
   publicAvailableRegistriesSchema,
+  type DocsIndex,
+  docsIndexSchema,
 } from "@/src/schema";
+import { CliError } from "@/src/utils/error";
+
+const FETCH_TIMEOUT_MS = 10_000;
+
+async function fetchWithTimeout(url: string, timeoutMs = FETCH_TIMEOUT_MS): Promise<Response> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { signal: controller.signal });
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new CliError({
+        message: `요청 시간이 초과되었어요 (${timeoutMs}ms): ${url}`,
+        hint: "네트워크 상태를 확인하고 다시 시도해주세요.",
+      });
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function fetchDocsIndex({ baseUrl }: { baseUrl: string }): Promise<DocsIndex> {
+  const response = await fetch(`${baseUrl}/__docs__/index.json`);
+
+  if (!response.ok)
+    throw new CliError({
+      message: `문서 목록을 가져오지 못했어요: ${response.status} ${response.statusText}`,
+    });
+
+  const data = await response.json();
+  const { success, data: parsed, error } = docsIndexSchema.safeParse(data);
+
+  if (!success)
+    throw new CliError({
+      message: `문서 목록 파싱에 실패했어요: ${error?.message}`,
+    });
+
+  return parsed;
+}
 
 export async function fetchAvailableRegistries({
   baseUrl,
@@ -79,6 +121,46 @@ async function fetchRegistryItem({
   return parsedItem;
 }
 
+export async function fetchLatestVersion(packageName: string): Promise<string> {
+  const response = await fetchWithTimeout(`https://registry.npmjs.org/${packageName}/latest`);
+
+  if (!response.ok) {
+    throw new CliError({
+      message: `${packageName}의 최신 버전을 가져오지 못했어요: ${response.status} ${response.statusText}`,
+    });
+  }
+
+  const data = await response.json();
+  if (!data || typeof data !== "object" || typeof data.version !== "string") {
+    throw new CliError({
+      message: `${packageName} 최신 버전 응답 형식이 올바르지 않아요.`,
+    });
+  }
+  return data.version;
+}
+
+export async function fetchChangelog({
+  baseUrl,
+  packageSlug,
+  version,
+}: {
+  baseUrl: string;
+  packageSlug: string;
+  version: string;
+}): Promise<string> {
+  const url = `${baseUrl}/llms/react/updates/changelog/${packageSlug}/${encodeURIComponent(version)}.txt`;
+  const response = await fetchWithTimeout(url);
+
+  if (!response.ok) {
+    throw new CliError({
+      message: `변경사항을 가져오지 못했어요: ${response.status} ${response.statusText}`,
+      hint: `${url} 에 접근할 수 있는지 확인해주세요.`,
+    });
+  }
+
+  return response.text();
+}
+
 export async function fetchRegistryItems({
   baseUrl,
   registryId,