@seed-design/cli 1.4.0-alpha.0 → 1.4.0

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").mockResolvedValue(
+      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").mockResolvedValue(
+      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,195 @@
+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 assertHasCommandAction<T extends { commandAction?: unknown }>(
+  command: T,
+  name: string,
+): asserts command is T & { commandAction: NonNullable<T["commandAction"]> } {
+  if (!command.commandAction) {
+    throw new Error(`Command has no action handler: ${name}`);
+  }
+}
+
+function getCommand(cli: CAC, name: string) {
+  const command = cli.commands.find((item) => item.name === name);
+
+  if (!command) {
+    throw new Error(`Command not found: ${name}`);
+  }
+
+  assertHasCommandAction(command, 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();
+  });
+});

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

@@ -0,0 +1,150 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { createServer, type Server } from "node:http";
+import path from "node:path";
+
+const repoRoot = path.resolve(import.meta.dir, "../../../..");
+
+const docsIndex = {
+  categories: [
+    {
+      id: "lynx",
+      label: "Lynx",
+      sections: [
+        {
+          id: "components",
+          label: "Components",
+          items: [
+            {
+              id: "action-button",
+              title: "Action Button",
+              docUrl: "/lynx/components/action-button",
+            },
+            {
+              id: "checkbox",
+              title: "Checkbox",
+              docUrl: "/lynx/components/checkbox",
+              snippetKey: "lynx/ui:checkbox",
+              snippets: [{ label: "checkbox", path: "checkbox.tsx" }],
+            },
+          ],
+        },
+      ],
+    },
+  ],
+};
+
+describe("docs command", () => {
+  let server: Server;
+  let baseUrl: string;
+  const requests: string[] = [];
+
+  beforeAll(async () => {
+    server = createServer((request, response) => {
+      const url = request.url ? new URL(request.url, "http://127.0.0.1") : undefined;
+      const pathname = url?.pathname ?? "/";
+      requests.push(pathname);
+
+      if (pathname === "/__docs__/index.json") {
+        response.writeHead(200, { "Content-Type": "application/json" });
+        response.end(JSON.stringify(docsIndex));
+        return;
+      }
+
+      response.writeHead(404, { "Content-Type": "text/plain" });
+      response.end("Not found");
+    });
+
+    await new Promise<void>((resolve) => {
+      server.listen(0, "127.0.0.1", resolve);
+    });
+
+    const address = server.address();
+    if (!address || typeof address === "string") {
+      throw new Error("Failed to start test docs server");
+    }
+    baseUrl = `http://127.0.0.1:${address.port}`;
+  });
+
+  afterAll(async () => {
+    await new Promise<void>((resolve, reject) => {
+      server.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+  });
+
+  async function runDocsCommand(args: string[]) {
+    const proc = Bun.spawn({
+      cmd: [process.execPath, "packages/cli/src/index.ts", "docs", ...args, "-u", baseUrl],
+      cwd: repoRoot,
+      env: {
+        ...process.env,
+        DISABLE_TELEMETRY: "true",
+        FORCE_COLOR: "0",
+      },
+      stderr: "pipe",
+      stdout: "pipe",
+    });
+
+    const [exitCode, stdout, stderr] = await Promise.all([
+      proc.exited,
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    return { exitCode, stderr, stdout };
+  }
+
+  it("resolves unquoted Lynx component queries to docs and llms links", async () => {
+    requests.length = 0;
+    const result = await runDocsCommand(["lynx", "action-button"]);
+
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `docs command failed\nbaseUrl:${baseUrl}\nrequests:${requests.join(",")}\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+      );
+    }
+    expect(result.stdout).toContain("- docs: http://");
+    expect(result.stdout).toContain("/lynx/components/action-button");
+    expect(result.stdout).toContain("- llms.txt: http://");
+    expect(result.stdout).toContain("/llms/lynx/components/action-button.txt");
+    expect(result.stdout).not.toContain("- snippet:");
+  });
+
+  it("prints Lynx snippet URLs for quoted Lynx component queries", async () => {
+    requests.length = 0;
+    const result = await runDocsCommand(["lynx checkbox"]);
+
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `docs command failed\nbaseUrl:${baseUrl}\nrequests:${requests.join(",")}\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+      );
+    }
+    expect(result.stdout).toContain("- docs: http://");
+    expect(result.stdout).toContain("/lynx/components/checkbox");
+    expect(result.stdout).toContain("- llms.txt: http://");
+    expect(result.stdout).toContain("/llms/lynx/components/checkbox.txt");
+    expect(result.stdout).toContain(
+      "- snippet: https://raw.githubusercontent.com/daangn/seed-design/refs/heads/dev/docs/registry/lynx/ui/checkbox.tsx",
+    );
+  });
+
+  it("resolves registry-key queries with an explicit framework", async () => {
+    requests.length = 0;
+    const result = await runDocsCommand(["ui:checkbox", "--framework", "lynx"]);
+
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `docs command failed\nbaseUrl:${baseUrl}\nrequests:${requests.join(",")}\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+      );
+    }
+    expect(result.stdout).toContain("- docs: http://");
+    expect(result.stdout).toContain("/lynx/components/checkbox");
+    expect(result.stdout).toContain(
+      "- snippet: https://raw.githubusercontent.com/daangn/seed-design/refs/heads/dev/docs/registry/lynx/ui/checkbox.tsx",
+    );
+  });
+});

package/src/types/shims.d.ts

@@ -0,0 +1,11 @@
+declare module "@babel/plugin-transform-typescript";
+
+declare module "@npmcli/disparity-colors" {
+  /**
+   * Colorizes unified diff output with ANSI escape codes.
+   *
+   * @param str - A unified diff format string.
+   * @param opts.headerLength - Number of lines at the start of the diff to colorize as header.
+   */
+  export default function colorize(str: string, opts?: { headerLength?: number }): string;
+}

package/src/utils/analytics.ts

@@ -3,12 +3,27 @@ import * as p from "@clack/prompts";
 import { getRawConfig } from "./get-config";
 
 const EVENT_PREFIX = "seed_cli";
+const COMMAND_STATUSES = ["completed", "cancelled", "failed"] as const;
 
 interface TrackOptions {
   event: string;
   properties?: Record<string, unknown>;
 }
 
+interface TrackCommandOutcomeOptions {
+  command: string;
+  status: (typeof COMMAND_STATUSES)[number];
+  result?: string;
+  properties?: Record<string, unknown>;
+}
+
+interface TrackCommandFailureOptions {
+  command: string;
+  error: unknown;
+  result?: string;
+  properties?: Record<string, unknown>;
+}
+
 /**
  * 텔레메트리 활성화 여부를 확인합니다.
  * 우선순위:
@@ -48,6 +63,24 @@ const sessionId = generateSessionId();
 // 세션당 한 번만 메시지 표시
 let hasShownMessage = false;
 
+function omitUndefined(properties: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(properties).filter(([, value]) => value !== undefined),
+  );
+}
+
+function getSafeErrorType(error: unknown): string {
+  if (error instanceof Error && error.name) {
+    return error.name;
+  }
+
+  if (typeof error === "object" && error !== null) {
+    return error.constructor?.name ?? "Object";
+  }
+
+  return typeof error;
+}
+
 /**
  * PostHog에 이벤트를 전송합니다.
  */
@@ -76,7 +109,7 @@ async function track(cwd: string, { event, properties = {} }: TrackOptions): Pro
   // PostHog API 호출 (fire-and-forget)
   try {
     if (!process.env.POSTHOG_HOST || !process.env.POSTHOG_API_KEY) {
-      console.warn("[Analytics] Missing POSTHOG_HOST or POSTHOG_API_KEY");
+      console.error("[Telemetry] POSTHOG_HOST 또는 POSTHOG_API_KEY가 없어서 이벤트를 전송하지 않아요.");
       return;
     }
 
@@ -113,6 +146,37 @@ async function track(cwd: string, { event, properties = {} }: TrackOptions): Pro
   }
 }
 
+async function trackCommandOutcome(
+  cwd: string,
+  { command, status, result, properties = {} }: TrackCommandOutcomeOptions,
+): Promise<void> {
+  await track(cwd, {
+    event: command,
+    properties: omitUndefined({
+      status,
+      result,
+      ...properties,
+    }),
+  });
+}
+
+async function trackCommandFailure(
+  cwd: string,
+  { command, error, result, properties = {} }: TrackCommandFailureOptions,
+): Promise<void> {
+  await trackCommandOutcome(cwd, {
+    command,
+    status: "failed",
+    result,
+    properties: omitUndefined({
+      error_type: getSafeErrorType(error),
+      ...properties,
+    }),
+  });
+}
+
 export const analytics = {
   track,
+  trackCommandFailure,
+  trackCommandOutcome,
 };

package/src/utils/compatibility.ts

@@ -9,9 +9,6 @@ import { highlight } from "./color";
 const REACT_COMPAT_PACKAGES = ["@seed-design/react", "@seed-design/css"] as const;
 const LYNX_COMPAT_PACKAGES = ["@seed-design/lynx-react", "@seed-design/lynx-css"] as const;
 
-/** @deprecated Use getCompatPackageNames(framework) instead */
-export const COMPAT_PACKAGE_NAMES = REACT_COMPAT_PACKAGES;
-
 export type CompatPackageName =
   | (typeof REACT_COMPAT_PACKAGES)[number]
   | (typeof LYNX_COMPAT_PACKAGES)[number];

package/src/utils/fetch.ts

@@ -12,6 +12,26 @@ import {
 } 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`);
 
@@ -108,6 +128,78 @@ async function fetchRegistryItem({
   return parsedItem;
 }
 
+export async function fetchLlmsTxt({ url }: { url: string }): Promise<string> {
+  const response = await fetchWithTimeout(url);
+
+  if (!response.ok) {
+    throw new CliError({
+      message: `llms.txt를 가져오지 못했어요: ${response.status} ${response.statusText}`,
+      hint: `${url} 에 접근할 수 있는지 확인해주세요.`,
+    });
+  }
+
+  return response.text();
+}
+
+/**
+ * Try fetching llms.txt content with fallback URL patterns.
+ * 1. {baseUrl}/llms/{query}.txt
+ * 2. {baseUrl}/llms/{query}/llms.txt (for package changelog index)
+ */
+export async function tryFetchLlmsTxt({
+  baseUrl,
+  query,
+}: {
+  baseUrl: string;
+  query: string;
+}): Promise<string> {
+  const normalizedQuery = query.startsWith("/") ? query.slice(1) : query;
+
+  const urls = [
+    `${baseUrl}/llms/${normalizedQuery}.txt`,
+    `${baseUrl}/llms/${normalizedQuery}/llms.txt`,
+  ];
+
+  let lastError: unknown;
+
+  for (const url of urls) {
+    let response: Response;
+    try {
+      response = await fetchWithTimeout(url);
+    } catch (error) {
+      lastError = error;
+      continue;
+    }
+
+    if (response.ok) {
+      return response.text();
+    }
+
+    // 404 → try next URL candidate
+    if (response.status === 404) {
+      lastError = new CliError({
+        message: `llms.txt를 찾을 수 없어요: ${normalizedQuery}`,
+        hint: `다음 경로를 시도했어요:\n${urls.map((u) => `  - ${u}`).join("\n")}`,
+      });
+      continue;
+    }
+
+    // Non-404 errors (5xx, 401, etc.) — propagate immediately
+    throw new CliError({
+      message: `llms.txt 요청이 실패했어요: ${response.status} ${response.statusText}`,
+      hint: `URL: ${url}`,
+    });
+  }
+
+  throw (
+    lastError ??
+    new CliError({
+      message: `llms.txt를 찾을 수 없어요: ${normalizedQuery}`,
+      hint: `다음 경로를 시도했어요:\n${urls.map((u) => `  - ${u}`).join("\n")}`,
+    })
+  );
+}
+
 export async function fetchRegistryItems({
   baseUrl,
   framework,

package/src/utils/install.ts

@@ -31,7 +31,7 @@ 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 command = [addCommand, isDev, ...depsToInstall].filter((v): v is string => Boolean(v));
   const commandLabel = `${packageManager} ${command.join(" ")}`;
 
   try {

package/src/utils/resolve-dependencies.ts

@@ -1,4 +1,4 @@
-import type { PublicRegistry, PublicRegistryItem } from "@/src/schema";
+import type { PublicRegistry } from "@/src/schema";
 
 export function resolveDependencies({
   selectedItemKeys,
@@ -13,7 +13,7 @@ export function resolveDependencies({
   const registryItemsToAdd: { registryId: string; items: PublicRegistry["items"] }[] = [];
   const npmDependenciesToAdd = new Set<string>();
 
-  function collectRegistryItemsToAdd(registryId: string, item: PublicRegistryItem) {
+  function collectRegistryItemsToAdd(registryId: string, item: PublicRegistry["items"][number]) {
     const registryFoundToAdd = registryItemsToAdd.find((r) => r.registryId === registryId);
 
     // if already added, skip