@seed-design/cli 1.2.0 → 1.2.2

package/src/utils/error.ts

@@ -0,0 +1,160 @@
+import * as p from "@clack/prompts";
+import { ZodError } from "zod";
+import { highlight } from "./color";
+
+interface CliErrorOptions {
+  message: string;
+  hint?: string;
+  details?: string[];
+  cause?: unknown;
+}
+
+interface HandleCliErrorOptions {
+  defaultMessage: string;
+  defaultHint?: string;
+  verbose?: boolean;
+}
+
+interface ExecaLikeError {
+  command?: string;
+  escapedCommand?: string;
+  exitCode?: number;
+  shortMessage?: string;
+  stderr?: string;
+  stdout?: string;
+  stack?: string;
+}
+
+export class CliError extends Error {
+  hint?: string;
+  details: string[];
+
+  constructor({ message, hint, details = [], cause }: CliErrorOptions) {
+    super(message, { cause });
+    this.name = "CliError";
+    this.hint = hint;
+    this.details = details;
+  }
+}
+
+export class CliCancelError extends Error {
+  constructor(message = "작업이 취소됐어요.") {
+    super(message);
+    this.name = "CliCancelError";
+  }
+}
+
+export function isCliCancelError(error: unknown): error is CliCancelError {
+  return error instanceof CliCancelError;
+}
+
+export function isVerboseMode(options: unknown): boolean {
+  if (!options || typeof options !== "object") return false;
+  if (!("verbose" in options)) return false;
+
+  return options.verbose === true;
+}
+
+function normalizeError(
+  error: unknown,
+  defaultHint?: string,
+): {
+  reason: string;
+  hint?: string;
+  details: string[];
+  stack?: string;
+} {
+  if (error instanceof CliError) {
+    return {
+      reason: error.message,
+      hint: error.hint ?? defaultHint,
+      details: error.details,
+      stack: toStack(error.cause ?? error),
+    };
+  }
+
+  if (error instanceof ZodError) {
+    const issues = error.issues.map((issue) => {
+      const path = issue.path.join(".") || "(root)";
+      return `${path}: ${issue.message}`;
+    });
+
+    return {
+      reason: "입력값 또는 설정 파일 형식이 올바르지 않아요.",
+      hint: defaultHint,
+      details: issues,
+      stack: error.stack,
+    };
+  }
+
+  if (error instanceof Error) {
+    const execaLike = error as ExecaLikeError;
+    const details: string[] = [];
+
+    if (execaLike.escapedCommand || execaLike.command) {
+      details.push(`실행 명령어: ${execaLike.escapedCommand ?? execaLike.command}`);
+    }
+    if (typeof execaLike.exitCode === "number") {
+      details.push(`종료 코드: ${execaLike.exitCode}`);
+    }
+    if (execaLike.stderr?.trim()) {
+      details.push(`stderr: ${execaLike.stderr.trim()}`);
+    } else if (execaLike.stdout?.trim()) {
+      details.push(`stdout: ${execaLike.stdout.trim()}`);
+    }
+
+    return {
+      reason: execaLike.shortMessage ?? error.message,
+      hint: defaultHint,
+      details,
+      stack: error.stack,
+    };
+  }
+
+  if (typeof error === "string") {
+    return {
+      reason: error,
+      hint: defaultHint,
+      details: [],
+    };
+  }
+
+  return {
+    reason: "알 수 없는 오류가 발생했어요.",
+    hint: defaultHint,
+    details: [],
+  };
+}
+
+function toStack(error: unknown): string | undefined {
+  if (error instanceof Error) {
+    return error.stack;
+  }
+
+  return undefined;
+}
+
+export function handleCliError(
+  error: unknown,
+  { defaultMessage, defaultHint, verbose = false }: HandleCliErrorOptions,
+): void {
+  const normalized = normalizeError(error, defaultHint);
+
+  p.log.error(defaultMessage);
+  p.log.error(`원인: ${normalized.reason}`);
+
+  for (const detail of normalized.details) {
+    p.log.info(detail);
+  }
+
+  if (normalized.hint) {
+    p.log.info(`해결 힌트: ${normalized.hint}`);
+  }
+
+  if (verbose && normalized.stack) {
+    p.log.message(highlight("\n[verbose] stack trace"));
+    p.log.message(normalized.stack);
+  }
+
+  p.outro(highlight("작업에 실패했어요."));
+}

package/src/utils/get-config.ts

@@ -1,9 +1,8 @@
 import * as p from "@clack/prompts";
 import { cosmiconfig } from "cosmiconfig";
-import { execa } from "execa";
 import { z } from "zod";
-import { highlight } from "./color";
-import { getPackageManager } from "./get-package-manager";
+import { CliCancelError, CliError } from "./error";
+import { DEFAULT_INIT_CONFIG, writeInitConfigFile } from "./init-config";
 
 const MODULE_NAME = "seed-design";
 
@@ -23,31 +22,45 @@ export const configSchema = z
 
 export type Config = z.infer<typeof configSchema>;
 
-export async function getConfig(cwd: string) {
+export async function getConfig(cwd: string): Promise<Config> {
   const config = await getRawConfig(cwd);
-  if (!config) return null;
+  if (config) return config;
 
-  return configSchema.parse(config);
-}
+  p.log.error("프로젝트 루트 경로에 `seed-design.json` 파일이 없어요.");
 
-export async function getRawConfig(cwd: string): Promise<Config | null> {
-  try {
-    const configResult = await explorer.search(cwd);
-    return configSchema.parse(configResult.config);
-  } catch {
-    p.log.error("프로젝트 루트 경로에 `seed-design.json` 파일이 없어요.");
+  const isConfirm = await p.confirm({ message: "seed-design.json 파일을 생성하시겠어요?" });
 
-    const isConfirm = await p.confirm({ message: "seed-design.json 파일을 생성하시겠어요?" });
-
-    if (!isConfirm) {
-      p.outro(highlight("작업이 취소됐어요."));
-      process.exit(1);
-    }
+  if (p.isCancel(isConfirm) || !isConfirm) {
+    throw new CliCancelError();
+  }
 
-    const packageManager = await getPackageManager(cwd);
+  try {
+    await writeInitConfigFile({
+      cwd,
+      config: DEFAULT_INIT_CONFIG,
+    });
+    p.log.message("seed-design.json 파일이 생성됐어요.");
+    return configSchema.parse(DEFAULT_INIT_CONFIG);
+  } catch (error) {
+    throw new CliError({
+      message: "seed-design.json 파일 생성에 실패했어요.",
+      hint: "디렉토리 쓰기 권한과 경로를 확인한 뒤 다시 시도해보세요.",
+      cause: error,
+    });
+  }
+}
 
-    await execa(packageManager, ["seed-design", "init", "--default"], { cwd });
+export async function getRawConfig(cwd: string): Promise<Config | null> {
+  const configResult = await explorer.search(cwd);
+  if (!configResult || configResult.isEmpty) return null;
 
-    p.log.message("seed-design.json 파일이 생성됐어요.");
+  try {
+    return configSchema.parse(configResult.config);
+  } catch (error) {
+    throw new CliError({
+      message: "seed-design.json 형식이 올바르지 않아요.",
+      hint: "https://seed-design.com/react/getting-started/cli/configuration 문서를 참고해 주세요.",
+      cause: error,
+    });
   }
 }

package/src/utils/get-package-info.ts

@@ -4,15 +4,15 @@ import type { PackageJson } from "type-fest";
 
 const PACKAGE_JSON = "package.json";
 
-function getPackagePath() {
-  const packageJsonPath = findup(PACKAGE_JSON);
+function getPackagePath(cwd = process.cwd()) {
+  const packageJsonPath = findup(PACKAGE_JSON, { cwd });
   if (!packageJsonPath) {
     throw new Error("No package.json file found in the project.");
   }
   return packageJsonPath;
 }
 
-export function getPackageInfo() {
-  const packageJsonPath = getPackagePath();
+export function getPackageInfo(cwd = process.cwd()) {
+  const packageJsonPath = getPackagePath(cwd);
   return fs.readJSONSync(packageJsonPath) as PackageJson;
 }

package/src/utils/init-config.ts

@@ -0,0 +1,67 @@
+import * as p from "@clack/prompts";
+import fs from "fs-extra";
+import path from "path";
+import { highlight } from "./color";
+import { CliCancelError } from "./error";
+
+import type { Config } from "./get-config";
+
+export const DEFAULT_INIT_CONFIG: Config = {
+  rsc: false,
+  tsx: true,
+  path: "./seed-design",
+  telemetry: true,
+};
+
+export async function promptInitConfig(): Promise<Config> {
+  const group = await p.group(
+    {
+      tsx: () =>
+        p.confirm({
+          message: `${highlight("TypeScript")}를 사용중이신가요?`,
+          initialValue: DEFAULT_INIT_CONFIG.tsx,
+        }),
+      rsc: () =>
+        p.confirm({
+          message: `${highlight("React Server Components")}를 사용중이신가요?`,
+          initialValue: DEFAULT_INIT_CONFIG.rsc,
+        }),
+      path: () =>
+        p.text({
+          message: `${highlight("seed-design 폴더")} 경로를 입력해주세요. (기본값은 프로젝트 루트에 생성됩니다.)`,
+          initialValue: DEFAULT_INIT_CONFIG.path,
+          defaultValue: DEFAULT_INIT_CONFIG.path,
+          placeholder: DEFAULT_INIT_CONFIG.path,
+        }),
+      telemetry: () =>
+        p.confirm({
+          message: `개선을 위해 ${highlight("익명 사용 데이터")}를 수집할까요?`,
+          initialValue: DEFAULT_INIT_CONFIG.telemetry,
+        }),
+    },
+    {
+      onCancel: () => {
+        throw new CliCancelError();
+      },
+    },
+  );
+
+  return group;
+}
+
+export async function writeInitConfigFile({
+  cwd,
+  config,
+}: {
+  cwd: string;
+  config: Config;
+}): Promise<{ relativePath: string; targetPath: string }> {
+  const targetPath = path.resolve(cwd, "seed-design.json");
+  await fs.writeFile(targetPath, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+  const relativePath = path.relative(process.cwd(), targetPath);
+
+  return {
+    relativePath,
+    targetPath,
+  };
+}

package/src/utils/install.ts

@@ -1,5 +1,6 @@
 import * as p from "@clack/prompts";
 import { execa } from "execa";
+import { CliError } from "./error";
 import { getPackageManager } from "./get-package-manager";
 import { getPackageInfo } from "./get-package-info";
 
@@ -12,7 +13,7 @@ interface InstallDependenciesProps {
 export async function installDependencies({ cwd, deps, dev = false }: InstallDependenciesProps) {
   const { start, stop } = p.spinner();
   const packageManager = await getPackageManager(cwd);
-  const packageInfo = getPackageInfo();
+  const packageInfo = getPackageInfo(cwd);
 
   // 이미 설치된 의존성 필터링
   const existingDeps = {
@@ -31,12 +32,18 @@ export async function installDependencies({ cwd, deps, dev = false }: InstallDep
   const isDev = dev ? "-D" : null;
   const addCommand = packageManager === "npm" ? "install" : "add";
   const command = [addCommand, isDev, ...depsToInstall].filter(Boolean);
+  const commandLabel = `${packageManager} ${command.join(" ")}`;
 
   try {
     await execa(packageManager, command, { cwd });
   } catch (error) {
-    console.error(`의존성 설치 실패: ${error}`);
-    process.exit(1);
+    stop("의존성 설치에 실패했어요.");
+    throw new CliError({
+      message: "의존성 설치에 실패했어요.",
+      hint: "네트워크 상태를 확인하고, 설치 명령어를 직접 실행해 상세 오류를 확인해보세요.",
+      details: [`실행 명령어: ${commandLabel}`],
+      cause: error,
+    });
   }
 
   stop("의존성 설치가 완료됐어요.");

package/src/utils/write.ts

@@ -15,14 +15,14 @@ export async function writeRegistryItemSnippets({
   cwd,
   baseUrl,
   config,
-  overwrite = false,
+  onDiff,
 }: {
   registryItemsToAdd: { registryId: string; items: PublicRegistry["items"] }[];
   rootPath: string;
   cwd: string;
   baseUrl: string;
   config: Config;
-  overwrite?: boolean;
+  onDiff?: "overwrite" | "backup";
 }) {
   const registryResult: { name: string; path: string }[] = [];
 
@@ -74,9 +74,17 @@ export async function writeRegistryItemSnippets({
             continue;
           }
 
+          const filename = path.basename(filePath);
+          const ext = path.extname(filePath);
+          const base = path.basename(filePath, ext);
+          const timestamp = Date.now();
+          const legacyFilename = `legacy-${base}-${timestamp}${ext}`;
+
           // diff가 있는 경우
-          if (!overwrite) {
-            // diff 생성 및 색상 적용
+          const action = await (async () => {
+            if (onDiff) return onDiff;
+
+            // interactive mode
             const patch = createPatch(relativePath, existingContent, content);
             const coloredDiff = colorize(patch);
 
@@ -85,13 +93,7 @@ export async function writeRegistryItemSnippets({
             );
             p.log.message(coloredDiff);
 
-            const filename = path.basename(filePath);
-            const ext = path.extname(filePath);
-            const base = path.basename(filePath, ext);
-            const timestamp = Date.now();
-            const legacyFilename = `legacy-${base}-${timestamp}${ext}`;
-
-            const action = await p.select({
+            return p.select({
               message:
                 "현재 파일에 스타일 변경, 로깅 등 커스터마이징이 적용되어 있는 경우 신규 파일에 동일한 커스터마이징을 적용하는 것을 검토해보세요.",
               options: [
@@ -103,20 +105,20 @@ export async function writeRegistryItemSnippets({
                 { value: "skip", label: "새 파일 받지 않고 그대로 두기" },
               ],
             });
+          })();
 
-            if (p.isCancel(action) || action === "skip") {
-              p.log.info(`${highlight(relativePath)}: 파일을 받지 않고 건너뛰었어요.`);
-              continue;
-            }
-
-            if (action === "backup") {
-              const dir = path.dirname(filePath);
-              const legacyPath = path.join(dir, legacyFilename);
-              await fs.rename(filePath, legacyPath);
-              p.log.info(
-                `${highlight(relativePath)}: 기존 파일을 ${highlight(path.relative(cwd, legacyPath))}로 옮겼어요.`,
-              );
-            }
+          if (p.isCancel(action) || action === "skip") {
+            p.log.info(`${highlight(relativePath)}: 파일을 받지 않고 건너뛰었어요.`);
+            continue;
+          }
+
+          if (action === "backup") {
+            const dir = path.dirname(filePath);
+            const legacyPath = path.join(dir, legacyFilename);
+            await fs.rename(filePath, legacyPath);
+            p.log.info(
+              `${highlight(relativePath)}: 기존 파일을 ${highlight(path.relative(cwd, legacyPath))}로 옮겼어요.`,
+            );
           }
         }