@seed-design/cli 1.3.1 → 1.3.3

package/src/commands/docs.ts

@@ -1,4 +1,4 @@
-import { fetchDocsIndex } from "@/src/utils/fetch";
+import { fetchDocsIndex, fetchLlmsTxt, tryFetchLlmsTxt } from "@/src/utils/fetch";
 import * as p from "@clack/prompts";
 import type { CAC } from "cac";
 import { z } from "zod";
@@ -20,6 +20,7 @@ const GITHUB_SNIPPET_BASE =
 const docsOptionsSchema = z.object({
   query: z.string().optional(),
   baseUrl: z.string().optional(),
+  raw: z.boolean(),
 });
 
 function buildSnippetUrl(registryId: string, snippetPath: string): string {
@@ -232,15 +233,22 @@ export const docsCommand = (cli: CAC) => {
     .option("-u, --baseUrl <baseUrl>", `레지스트리의 기본 URL (기본값: ${BASE_URL})`, {
       default: BASE_URL,
     })
+    .option("--raw", "llms.txt 내용을 직접 가져와 출력합니다. LLM 파이프에 유용합니다.", {
+      default: false,
+    })
     .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")
+    .example("seed-design docs react/updates/changelog --raw")
     .action(async (query, opts) => {
       const startTime = Date.now();
       const verbose = isVerboseMode(opts);
-      p.intro("seed-design docs");
+      const raw = opts.raw ?? false;
+      const trackCwd = process.cwd();
+
+      if (!raw) p.intro("seed-design docs");
 
       try {
         const parsed = docsOptionsSchema.safeParse({ query, ...opts });
@@ -251,10 +259,19 @@ export const docsCommand = (cli: CAC) => {
         const { data: options } = parsed;
         const baseUrl = options.baseUrl ?? BASE_URL;
 
-        const { start, stop } = p.spinner();
-        start("문서 목록을 가져오고 있어요...");
+        if (options.raw && !options.query) {
+          throw new CliError({
+            message: "--raw 모드에서는 쿼리가 필요해요.",
+            hint: "예: `seed-design docs react/updates/changelog --raw`",
+          });
+        }
 
         const docsIndex = await (async () => {
+          if (raw) {
+            return await fetchDocsIndex({ baseUrl });
+          }
+          const { start, stop } = p.spinner();
+          start("문서 목록을 가져오고 있어요...");
           try {
             const index = await fetchDocsIndex({ baseUrl });
             stop("문서 목록을 가져왔어요.");
@@ -266,23 +283,31 @@ export const docsCommand = (cli: CAC) => {
         })();
 
         const { categories } = docsIndex;
-        let selectedItem: DocsItem;
+        let selectedItem: DocsItem | undefined;
+
+        // In --raw mode, wrap index resolution in try-catch to allow fallback to direct URL
+        const resolveFromIndex = async (): Promise<DocsItem | undefined> => {
+          if (options.query) {
+            const segments = parseQueryPath(options.query);
 
-        if (options.query) {
-          const segments = parseQueryPath(options.query);
+            // Deep paths (more than category/section/item) can't be resolved from index
+            // e.g., react/updates/changelog/react/1.2.9 — skip to fallback in --raw mode
+            if (raw && segments.length > 3) {
+              return undefined;
+            }
 
-          // Try to resolve as path: category / section / item
-          const matchedCategory = categories.find((c) => c.id === segments[0]);
+            // 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 (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 {
+              if (matchedSection && segments.length >= 3) {
+                // Full path: category/section/item
+                const matchedItem = matchedSection.items.find((i) => i.id === segments[2]);
+                if (matchedItem) {
+                  return matchedItem;
+                }
                 // Item not found in section — search within the section
                 const q = segments[2].toLowerCase();
                 const matched = matchedSection.items.filter(
@@ -306,15 +331,14 @@ export const docsCommand = (cli: CAC) => {
                   });
                 }
                 if (matched.length === 1) {
-                  selectedItem = matched[0];
-                } else {
-                  selectedItem = await selectItem(matched);
+                  return matched[0];
                 }
+                return await selectItem(matched);
+              }
+              if (matchedSection) {
+                // category/section — select item within section
+                return await selectItem(matchedSection.items);
               }
-            } 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) =>
@@ -329,7 +353,10 @@ export const docsCommand = (cli: CAC) => {
                 const sectionIds = matchedCategory.sections.map((s) => s.id);
                 const similarSections = findSimilar(segments[1], sectionIds);
                 const allItemIds = matchedCategory.sections.flatMap((s) =>
-                  s.items.map((i) => ({ path: `${matchedCategory.id}/${s.id}/${i.id}`, id: i.id })),
+                  s.items.map((i) => ({
+                    path: `${matchedCategory.id}/${s.id}/${i.id}`,
+                    id: i.id,
+                  })),
                 );
                 const similarItems = findSimilar(
                   segments[1],
@@ -352,29 +379,27 @@ export const docsCommand = (cli: CAC) => {
                 });
               }
               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;
+                return matched[0].item;
               }
+              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();
+              return 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 {
+            if (matchedCategory) {
+              // Single segment matching a category — drill into it
+              if (matchedCategory.sections.length === 1) {
+                return await selectItem(matchedCategory.sections[0].items);
+              }
               const section = await selectSection(matchedCategory.sections);
-              selectedItem = await selectItem(section.items);
+              return await selectItem(section.items);
             }
-          } else {
             // No category match — global search
             const matched = searchAllItems(categories, options.query);
 
@@ -386,22 +411,21 @@ export const docsCommand = (cli: CAC) => {
               });
             }
             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;
+              return matched[0].item;
             }
+            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();
+            return selected;
           }
-        } else {
-          // Full interactive flow: category → section → item
+
+          // No query — full interactive flow: category → section → item
           const category = await selectCategory(categories);
 
           let section: DocsSection;
@@ -411,34 +435,94 @@ export const docsCommand = (cli: CAC) => {
             section = await selectSection(category.sections);
           }
 
-          selectedItem = await selectItem(section.items);
+          return await selectItem(section.items);
+        };
+
+        // In --raw mode, swallow index resolution errors and fall back to direct URL fetch
+        if (raw) {
+          try {
+            selectedItem = await resolveFromIndex();
+          } catch (error) {
+            if (isCliCancelError(error)) throw error;
+            // index miss in raw mode → will use fallback
+          }
+        } else {
+          selectedItem = await resolveFromIndex();
         }
 
-        printDocsResult(selectedItem, baseUrl);
-        p.outro("완료했어요.");
+        if (raw) {
+          let content: string;
+          if (selectedItem) {
+            const llmsUrl = `${baseUrl}/llms${selectedItem.docUrl}.txt`;
+            content = await fetchLlmsTxt({ url: llmsUrl });
+          } else {
+            content = await tryFetchLlmsTxt({ baseUrl, query: options.query! });
+          }
+          console.log(content);
+        } else {
+          printDocsResult(selectedItem!, baseUrl);
+          p.outro("완료했어요.");
+        }
 
         const duration = Date.now() - startTime;
         try {
-          await analytics.track(process.cwd(), {
-            event: "docs",
+          await analytics.trackCommandOutcome(trackCwd, {
+            command: "docs",
+            status: "completed",
             properties: {
               query: options.query ?? null,
-              item_id: selectedItem.id,
-              has_snippet: !!(selectedItem.snippets && selectedItem.snippets.length > 0),
+              item_id: selectedItem?.id ?? options.query ?? null,
+              has_snippet: !!(selectedItem?.snippets && selectedItem.snippets.length > 0),
+              raw_mode: raw,
               duration_ms: duration,
             },
           });
         } catch (telemetryError) {
           if (verbose) {
-            console.error("[Telemetry] docs tracking failed:", telemetryError);
+            console.error("[Telemetry] docs 이벤트 전송에 실패했어요:", telemetryError);
           }
         }
       } catch (error) {
         if (isCliCancelError(error)) {
-          p.outro(highlight(error.message));
+          try {
+            await analytics.trackCommandOutcome(trackCwd, {
+              command: "docs",
+              status: "cancelled",
+              properties: {
+                raw_mode: raw,
+                duration_ms: Date.now() - startTime,
+              },
+            });
+          } catch (telemetryError) {
+            if (verbose) {
+              console.error("[Telemetry] docs 이벤트 전송에 실패했어요:", telemetryError);
+            }
+          }
+          if (!raw) p.outro(highlight(error.message));
           process.exit(0);
         }
 
+        try {
+          await analytics.trackCommandFailure(trackCwd, {
+            command: "docs",
+            error,
+            properties: {
+              raw_mode: raw,
+              duration_ms: Date.now() - startTime,
+            },
+          });
+        } catch (telemetryError) {
+          if (verbose) {
+            console.error("[Telemetry] docs 이벤트 전송에 실패했어요:", telemetryError);
+          }
+        }
+
+        if (raw) {
+          const msg = error instanceof Error ? error.message : String(error);
+          console.error(msg);
+          process.exit(1);
+        }
+
         handleCliError(error, {
           defaultMessage: "문서 조회에 실패했어요.",
           defaultHint: "`--verbose` 옵션으로 상세 오류를 확인해보세요.",

package/src/commands/init.ts

@@ -27,6 +27,7 @@ export const initCommand = (cli: CAC) => {
     .action(async (opts) => {
       const startTime = Date.now();
       const verbose = isVerboseMode(opts);
+      const trackCwd = typeof opts?.cwd === "string" ? opts.cwd : process.cwd();
       p.intro("seed-design.json 파일 생성");
 
       try {
@@ -78,8 +79,9 @@ export const initCommand = (cli: CAC) => {
         // init 성공 이벤트 추적
         const duration = Date.now() - startTime;
         try {
-          await analytics.track(options.cwd, {
-            event: "init",
+          await analytics.trackCommandOutcome(options.cwd, {
+            command: "init",
+            status: "completed",
             properties: {
               tsx: config.tsx,
               rsc: config.rsc,
@@ -90,15 +92,42 @@ export const initCommand = (cli: CAC) => {
           });
         } catch (telemetryError) {
           if (verbose) {
-            console.error("[Telemetry] init tracking failed:", telemetryError);
+            console.error("[Telemetry] init 이벤트 전송에 실패했어요:", telemetryError);
           }
         }
       } catch (error) {
         if (isCliCancelError(error)) {
+          try {
+            await analytics.trackCommandOutcome(trackCwd, {
+              command: "init",
+              status: "cancelled",
+              properties: {
+                duration_ms: Date.now() - startTime,
+              },
+            });
+          } catch (telemetryError) {
+            if (verbose) {
+              console.error("[Telemetry] init 이벤트 전송에 실패했어요:", telemetryError);
+            }
+          }
           p.outro(highlight(error.message));
           process.exit(0);
         }
 
+        try {
+          await analytics.trackCommandFailure(trackCwd, {
+            command: "init",
+            error,
+            properties: {
+              duration_ms: Date.now() - startTime,
+            },
+          });
+        } catch (telemetryError) {
+          if (verbose) {
+            console.error("[Telemetry] init 이벤트 전송에 실패했어요:", telemetryError);
+          }
+        }
+
         handleCliError(error, {
           defaultMessage: "seed-design.json 파일 생성에 실패했어요.",
           defaultHint: "`--verbose` 옵션으로 상세 오류를 확인해보세요.",

package/src/index.ts

@@ -5,7 +5,7 @@ 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";
 
@@ -23,7 +23,6 @@ async function main() {
   compatCommand(CLI);
   docsCommand(CLI);
   initCommand(CLI);
-  upgradeCommand(CLI);
 
   CLI.version(packageInfo.version || "1.0.0", "-v, --version");
   CLI.help();

package/src/tests/analytics.test.ts

@@ -0,0 +1,95 @@
+import { afterEach, beforeEach, describe, expect, it, mock, spyOn } from "bun:test";
+import fs from "fs-extra";
+import os from "os";
+import path from "path";
+import * as prompts from "@clack/prompts";
+import { analytics } from "../utils/analytics";
+
+describe("analytics command outcome tracking", () => {
+  const originalEnv = { ...process.env };
+  const tempDirs: string[] = [];
+
+  beforeEach(() => {
+    process.env.NODE_ENV = "prod";
+    process.env.POSTHOG_API_KEY = "test-api-key";
+    process.env.POSTHOG_HOST = "https://us.i.posthog.com";
+    delete process.env.DISABLE_TELEMETRY;
+    delete process.env.SEED_DISABLE_TELEMETRY;
+  });
+
+  afterEach(async () => {
+    process.env = { ...originalEnv };
+    mock.restore();
+
+    while (tempDirs.length > 0) {
+      const dir = tempDirs.pop();
+      if (dir) {
+        await fs.remove(dir);
+      }
+    }
+  });
+
+  async function createTempCwd() {
+    const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "seed-cli-analytics-"));
+    tempDirs.push(cwd);
+    return cwd;
+  }
+
+  it("command outcome payload에 status를 포함해야 한다", async () => {
+    const cwd = await createTempCwd();
+    const fetchSpy = spyOn(globalThis, "fetch").mockImplementation(
+      async () => new Response(null, { status: 200 }),
+    );
+    const infoSpy = spyOn(prompts.log, "info").mockImplementation(() => {});
+
+    await analytics.trackCommandOutcome(cwd, {
+      command: "add",
+      status: "completed",
+      properties: {
+        items_count: 2,
+      },
+    });
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    expect(infoSpy).toHaveBeenCalled();
+
+    const [, request] = fetchSpy.mock.calls[0] ?? [];
+    const payload = JSON.parse(String(request?.body));
+
+    expect(payload.event).toBe("seed_cli.add");
+    expect(payload.properties).toMatchObject({
+      status: "completed",
+      items_count: 2,
+      $process_person_profile: false,
+    });
+  });
+
+  it("failed outcome payload에는 error_type만 포함하고 message는 포함하지 않아야 한다", async () => {
+    const cwd = await createTempCwd();
+    const fetchSpy = spyOn(globalThis, "fetch").mockImplementation(
+      async () => new Response(null, { status: 200 }),
+    );
+    spyOn(prompts.log, "info").mockImplementation(() => {});
+
+    await analytics.trackCommandFailure(cwd, {
+      command: "docs",
+      error: new Error("sensitive details"),
+      properties: {
+        raw_mode: true,
+      },
+    });
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+
+    const [, request] = fetchSpy.mock.calls[0] ?? [];
+    const payload = JSON.parse(String(request?.body));
+
+    expect(payload.event).toBe("seed_cli.docs");
+    expect(payload.properties).toMatchObject({
+      status: "failed",
+      error_type: "Error",
+      raw_mode: true,
+    });
+    expect(payload.properties.error_message).toBeUndefined();
+  });
+});

package/src/tests/command-telemetry.test.ts

@@ -0,0 +1,185 @@
+import { beforeEach, describe, expect, it, mock, spyOn } from "bun:test";
+import type { CAC } from "cac";
+import { cac } from "cac";
+import { CliCancelError } from "../utils/error";
+import { analytics } from "../utils/analytics";
+
+const introMock = mock(() => {});
+const outroMock = mock(() => {});
+const infoMock = mock(() => {});
+const messageMock = mock(() => {});
+const errorMock = mock(() => {});
+const noteMock = mock(() => {});
+const spinnerStartMock = mock(() => {});
+const spinnerStopMock = mock(() => {});
+const promptInitConfigMock = mock(async () => ({
+  tsx: true,
+  rsc: false,
+  path: "./seed-design",
+  telemetry: true,
+}));
+const writeInitConfigFileMock = mock(async () => ({
+  relativePath: "seed-design.json",
+}));
+
+mock.module("@clack/prompts", () => ({
+  intro: introMock,
+  outro: outroMock,
+  note: noteMock,
+  log: {
+    info: infoMock,
+    message: messageMock,
+    error: errorMock,
+  },
+  spinner: () => ({
+    start: spinnerStartMock,
+    stop: spinnerStopMock,
+  }),
+  isCancel: () => false,
+}));
+
+mock.module("../utils/init-config", () => ({
+  DEFAULT_INIT_CONFIG: {
+    tsx: true,
+    rsc: false,
+    path: "./seed-design",
+    telemetry: true,
+  },
+  promptInitConfig: promptInitConfigMock,
+  writeInitConfigFile: writeInitConfigFileMock,
+}));
+
+const { addCommand } = await import("../commands/add");
+const { initCommand } = await import("../commands/init");
+
+function getCommand(cli: CAC, name: string) {
+  const command = cli.commands.find((item) => item.name === name);
+
+  if (!command) {
+    throw new Error(`Command not found: ${name}`);
+  }
+
+  return command;
+}
+
+describe("command telemetry", () => {
+  beforeEach(() => {
+    introMock.mockClear();
+    outroMock.mockClear();
+    infoMock.mockClear();
+    messageMock.mockClear();
+    errorMock.mockClear();
+    noteMock.mockClear();
+    spinnerStartMock.mockClear();
+    spinnerStopMock.mockClear();
+    promptInitConfigMock.mockClear();
+    writeInitConfigFileMock.mockClear();
+  });
+
+  it("init 성공 시 completed outcome을 전송해야 한다", async () => {
+    const trackCommandOutcomeSpy = spyOn(analytics, "trackCommandOutcome").mockImplementation(
+      async () => {},
+    );
+    const trackCommandFailureSpy = spyOn(analytics, "trackCommandFailure").mockImplementation(
+      async () => {},
+    );
+    const cli = cac("seed-design");
+    initCommand(cli);
+
+    await getCommand(cli, "init").commandAction({
+      cwd: "/tmp/seed-design",
+      yes: true,
+      default: false,
+    });
+
+    expect(writeInitConfigFileMock).toHaveBeenCalledTimes(1);
+    expect(trackCommandOutcomeSpy).toHaveBeenCalledWith(
+      "/tmp/seed-design",
+      expect.objectContaining({
+        command: "init",
+        status: "completed",
+        properties: expect.objectContaining({
+          yes_option: true,
+          telemetry: true,
+        }),
+      }),
+    );
+    expect(trackCommandFailureSpy).not.toHaveBeenCalled();
+
+    trackCommandOutcomeSpy.mockRestore();
+    trackCommandFailureSpy.mockRestore();
+  });
+
+  it("init 취소 시 cancelled outcome을 전송해야 한다", async () => {
+    const trackCommandOutcomeSpy = spyOn(analytics, "trackCommandOutcome").mockImplementation(
+      async () => {},
+    );
+    const trackCommandFailureSpy = spyOn(analytics, "trackCommandFailure").mockImplementation(
+      async () => {},
+    );
+    promptInitConfigMock.mockImplementationOnce(async () => {
+      throw new CliCancelError("작업이 취소됐어요.");
+    });
+
+    const exitSpy = spyOn(process, "exit").mockImplementation(((code?: number) => {
+      throw new Error(`EXIT:${code}`);
+    }) as never);
+
+    const cli = cac("seed-design");
+    initCommand(cli);
+
+    await expect(
+      getCommand(cli, "init").commandAction({
+        cwd: "/tmp/seed-design",
+        yes: false,
+        default: false,
+      }),
+    ).rejects.toThrow("EXIT:0");
+
+    expect(trackCommandOutcomeSpy).toHaveBeenCalledWith(
+      "/tmp/seed-design",
+      expect.objectContaining({
+        command: "init",
+        status: "cancelled",
+      }),
+    );
+    expect(trackCommandFailureSpy).not.toHaveBeenCalled();
+
+    exitSpy.mockRestore();
+    trackCommandOutcomeSpy.mockRestore();
+    trackCommandFailureSpy.mockRestore();
+  });
+
+  it("add 실패 시 failed outcome을 전송해야 한다", async () => {
+    const trackCommandFailureSpy = spyOn(analytics, "trackCommandFailure").mockImplementation(
+      async () => {},
+    );
+    const exitSpy = spyOn(process, "exit").mockImplementation(((code?: number) => {
+      throw new Error(`EXIT:${code}`);
+    }) as never);
+
+    const cli = cac("seed-design");
+    addCommand(cli);
+
+    await expect(
+      getCommand(cli, "add").commandAction([], {
+        all: true,
+        cwd: "/tmp/seed-design",
+        baseUrl: "https://seed-design.io",
+      }),
+    ).rejects.toThrow("EXIT:1");
+
+    expect(trackCommandFailureSpy).toHaveBeenCalledWith(
+      "/tmp/seed-design",
+      expect.objectContaining({
+        command: "add",
+        error: expect.objectContaining({
+          name: "CliError",
+        }),
+      }),
+    );
+
+    exitSpy.mockRestore();
+    trackCommandFailureSpy.mockRestore();
+  });
+});