kigumi 0.19.2 → 0.20.0

package/dist/chunk-L52LAS37.js

@@ -0,0 +1,1978 @@
+import {
+  CLI_VERSION,
+  DEFAULT_WEBAWESOME_VERSION,
+  GITHUB_ISSUES_URL,
+  GITHUB_RAW_BASE_URL,
+  GITHUB_REPO_URL,
+  WEB_AWESOME_FREE_PACKAGE,
+  WEB_AWESOME_PRO_PACKAGE,
+  detectTierSync,
+  getWebAwesomePackage
+} from "./chunk-F52T5BFP.js";
+import {
+  toKigumiAlias
+} from "./chunk-MIPVTLNR.js";
+
+// src/prompts/index.ts
+import * as clack from "@clack/prompts";
+var registered = null;
+function getPrompts() {
+  return registered ?? clack;
+}
+var confirm = (...args) => getPrompts().confirm(...args);
+var intro = (...args) => getPrompts().intro(...args);
+var outro = (...args) => getPrompts().outro(...args);
+var note = (...args) => getPrompts().note(...args);
+var select = (opts) => getPrompts().select(opts);
+var text = (...args) => getPrompts().text(...args);
+var multiselect = (opts) => getPrompts().multiselect(opts);
+var spinner = (...args) => getPrompts().spinner(...args);
+var isCancel = ((value) => getPrompts().isCancel(value));
+var log = {
+  info: (...args) => getPrompts().log.info(...args),
+  success: (...args) => getPrompts().log.success(...args),
+  warning: (...args) => getPrompts().log.warning(...args),
+  warn: (...args) => getPrompts().log.warn(...args),
+  error: (...args) => getPrompts().log.error(...args),
+  message: (...args) => getPrompts().log.message(...args),
+  step: (...args) => getPrompts().log.step(...args)
+};
+
+// src/output/console.ts
+import pc from "picocolors";
+var ClackSpinner = class {
+  spinner;
+  constructor(message) {
+    this.spinner = spinner();
+    this.spinner.start(message);
+  }
+  start(message) {
+    if (message) {
+      this.spinner.start(message);
+    }
+  }
+  message(text2) {
+    this.spinner.message(text2);
+  }
+  stop(message) {
+    this.spinner.stop(message || "Done");
+  }
+  error(message) {
+    this.spinner.stop(message || "Failed");
+  }
+};
+var ConsoleOutput = class {
+  intro(message) {
+    intro(pc.bgCyan(pc.black(` ${message} `)));
+  }
+  outro(message) {
+    outro(message);
+  }
+  info(message) {
+    log.info(message);
+  }
+  success(message) {
+    log.success(pc.green(message));
+  }
+  warning(message) {
+    log.warning(pc.yellow(message));
+  }
+  warn(message) {
+    this.warning(message);
+  }
+  error(message, error) {
+    if (error) {
+      if (error && typeof error === "object" && "format" in error && typeof error.format === "function") {
+        const formatted = error.format();
+        log.error(pc.red(formatted));
+      } else {
+        log.error(pc.red(message));
+        if (error.message) {
+          log.error(pc.dim(error.message));
+        }
+      }
+    } else {
+      log.error(pc.red(message));
+    }
+  }
+  note(title, message) {
+    note(message, title);
+  }
+  spinner(message) {
+    return new ClackSpinner(message);
+  }
+  log(message) {
+    if (process.env.DEBUG) {
+      log.message(message);
+    }
+  }
+};
+function getOutput() {
+  return new ConsoleOutput();
+}
+
+// src/output/index.ts
+var registeredOutput = null;
+function getOutput2() {
+  return registeredOutput ?? getOutput();
+}
+
+// src/checks/runner.ts
+var CheckRunner = class {
+  checks = [];
+  options;
+  constructor(options = {}) {
+    this.options = {
+      stopOnError: options.stopOnError ?? true,
+      parallel: options.parallel ?? false
+    };
+  }
+  /**
+   * Add a check to the runner
+   *
+   * @param check - Check to add
+   * @returns This runner (for chaining)
+   */
+  add(check) {
+    this.checks.push(check);
+    return this;
+  }
+  /**
+   * Add multiple checks
+   *
+   * @param checks - Checks to add
+   * @returns This runner (for chaining)
+   */
+  addAll(checks) {
+    this.checks.push(...checks);
+    return this;
+  }
+  /**
+   * Run all checks
+   *
+   * @param context - Check context
+   * @returns Array of check results
+   */
+  async run(context) {
+    if (this.checks.length === 0) {
+      return [];
+    }
+    if (this.options.parallel) {
+      return this.runParallel(context);
+    }
+    return this.runSequential(context);
+  }
+  /**
+   * Run checks sequentially
+   */
+  async runSequential(context) {
+    const results = [];
+    for (const check of this.checks) {
+      try {
+        const result = await check.run(context);
+        results.push(result);
+        if (this.options.stopOnError && !result.passed && result.severity === "error" /* ERROR */) {
+          break;
+        }
+      } catch (error) {
+        results.push({
+          passed: false,
+          severity: "error" /* ERROR */,
+          message: `Check "${check.name}" failed with error: ${error instanceof Error ? error.message : String(error)}`,
+          suggestion: ["Check the logs for more details"]
+        });
+        if (this.options.stopOnError) {
+          break;
+        }
+      }
+    }
+    return results;
+  }
+  /**
+   * Run checks in parallel
+   */
+  async runParallel(context) {
+    const promises = this.checks.map(async (check) => {
+      try {
+        return await check.run(context);
+      } catch (error) {
+        return {
+          passed: false,
+          severity: "error" /* ERROR */,
+          message: `Check "${check.name}" failed with error: ${error instanceof Error ? error.message : String(error)}`,
+          suggestion: ["Check the logs for more details"]
+        };
+      }
+    });
+    return Promise.all(promises);
+  }
+  /**
+   * Check if there are any errors in results
+   *
+   * @param results - Check results
+   * @returns True if there are errors
+   */
+  hasErrors(results) {
+    return results.some((r) => !r.passed && r.severity === "error" /* ERROR */);
+  }
+  /**
+   * Check if there are any warnings in results
+   *
+   * @param results - Check results
+   * @returns True if there are warnings
+   */
+  hasWarnings(results) {
+    return results.some(
+      (r) => !r.passed && r.severity === "warning" /* WARNING */
+    );
+  }
+  /**
+   * Get all errors from results
+   *
+   * @param results - Check results
+   * @returns Array of error results
+   */
+  getErrors(results) {
+    return results.filter(
+      (r) => !r.passed && r.severity === "error" /* ERROR */
+    );
+  }
+  /**
+   * Get all warnings from results
+   *
+   * @param results - Check results
+   * @returns Array of warning results
+   */
+  getWarnings(results) {
+    return results.filter(
+      (r) => !r.passed && r.severity === "warning" /* WARNING */
+    );
+  }
+  /**
+   * Format results as string
+   *
+   * @param results - Check results
+   * @returns Formatted string
+   */
+  formatResults(results) {
+    const errors = this.getErrors(results);
+    const warnings = this.getWarnings(results);
+    const parts = [];
+    if (errors.length > 0) {
+      parts.push(`Errors (${errors.length}):`);
+      errors.forEach((error) => {
+        parts.push(`  \u2717 ${error.message}`);
+      });
+    }
+    if (warnings.length > 0) {
+      if (parts.length > 0) parts.push("");
+      parts.push(`Warnings (${warnings.length}):`);
+      warnings.forEach((warning) => {
+        parts.push(`  \u26A0 ${warning.message}`);
+      });
+    }
+    return parts.join("\n");
+  }
+  /**
+   * Clear all checks
+   */
+  clear() {
+    this.checks = [];
+  }
+};
+
+// src/errors/base.ts
+var KigumiError = class extends Error {
+  code;
+  context;
+  suggestions;
+  exitCode;
+  constructor(code, message, details, suggestions = [], cause) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.exitCode = this.getExitCode(code);
+    this.context = {
+      code,
+      message,
+      details,
+      cause
+    };
+    this.suggestions = suggestions;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  /**
+   * Map error code to semantic exit code
+   *
+   * Exit codes:
+   * - 0: User cancelled (not an error)
+   * - 1: Configuration error
+   * - 2: Validation error
+   * - 3: Tier restriction error
+   * - 4: File system error
+   * - 5: Network/dependency error
+   * - 6: Pre-flight check error
+   */
+  getExitCode(code) {
+    if (code === 0 /* USER_CANCELLED */) return 0;
+    if (code >= 100 && code < 200) return 1;
+    if (code >= 200 && code < 300) return 2;
+    if (code >= 300 && code < 400) return 3;
+    if (code >= 400 && code < 500) return 4;
+    if (code >= 500 && code < 600) return 5;
+    if (code >= 600 && code < 700) return 6;
+    if (code >= 700 && code < 800) return 7;
+    return 1;
+  }
+  /**
+   * Format error for display to user
+   *
+   * Each error subclass can override this to provide custom formatting,
+   * but the default implementation provides a consistent format.
+   */
+  format() {
+    const parts = [];
+    parts.push(this.message);
+    if (this.context.details && Object.keys(this.context.details).length > 0) {
+      parts.push("");
+      parts.push("Details:");
+      for (const [key, value] of Object.entries(this.context.details)) {
+        parts.push(`  ${key}: ${JSON.stringify(value)}`);
+      }
+    }
+    if (this.context.cause) {
+      parts.push("");
+      parts.push(`Caused by: ${this.context.cause.message}`);
+    }
+    return parts.join("\n");
+  }
+  /**
+   * Get formatted suggestions
+   */
+  formatSuggestions() {
+    if (this.suggestions.length === 0) {
+      return "";
+    }
+    return this.suggestions.map((suggestion) => {
+      const steps = suggestion.steps.map((step, i) => `  ${i + 1}. ${step}`).join("\n");
+      return `${suggestion.title}:
+${steps}`;
+    }).join("\n\n");
+  }
+  /**
+   * Convert to JSON for logging/telemetry
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      exitCode: this.exitCode,
+      message: this.message,
+      context: this.context,
+      suggestions: this.suggestions,
+      stack: this.stack
+    };
+  }
+};
+var UserCancelledError = class extends KigumiError {
+  constructor(message = "Operation cancelled by user") {
+    super(0 /* USER_CANCELLED */, message);
+  }
+};
+var UnknownError = class _UnknownError extends KigumiError {
+  constructor(message, cause) {
+    super(
+      999 /* UNKNOWN */,
+      message,
+      { originalError: cause?.message },
+      [
+        {
+          title: "This is an unexpected error",
+          steps: [
+            `Please report this issue at: ${GITHUB_ISSUES_URL}`,
+            "Include the full error message and stack trace"
+          ]
+        }
+      ],
+      cause
+    );
+  }
+  /**
+   * Wrap any error with KigumiError structure
+   */
+  static from(error) {
+    if (error instanceof KigumiError) {
+      return error;
+    }
+    if (error instanceof Error) {
+      return new _UnknownError(
+        `An unexpected error occurred: ${error.message}`,
+        error
+      );
+    }
+    return new _UnknownError(`An unexpected error occurred: ${String(error)}`);
+  }
+};
+
+// src/errors/config.ts
+var ConfigNotFoundError = class extends KigumiError {
+  constructor(cwd) {
+    const suggestions = [
+      {
+        title: "Initialize kigumi in your project",
+        steps: [
+          "Run: kigumi init",
+          "Follow the prompts to configure your project",
+          "This will create kigumi.config.json"
+        ]
+      },
+      {
+        title: "Or create the config file manually",
+        steps: [
+          "Create kigumi.config.json in your project root",
+          "Add the required configuration fields",
+          `See: ${GITHUB_REPO_URL}#configuration`
+        ]
+      }
+    ];
+    super(
+      100 /* CONFIG_NOT_FOUND */,
+      "Configuration file not found",
+      { cwd, searchedFiles: ["kigumi.config.json", "kigumi.json"] },
+      suggestions
+    );
+  }
+};
+var ConfigInvalidError = class extends KigumiError {
+  constructor(errors, filePath) {
+    const suggestions = [
+      {
+        title: "Fix the configuration errors",
+        steps: [
+          ...errors.map((err) => `Fix: ${err}`),
+          "Ensure all required fields are present",
+          "Check that values match the expected types"
+        ]
+      },
+      {
+        title: "Or reinitialize the project",
+        steps: [
+          "Backup your current config",
+          "Run: kigumi init",
+          "Reconfigure with correct values"
+        ]
+      }
+    ];
+    super(
+      101 /* CONFIG_INVALID */,
+      "Configuration file is invalid",
+      { errors, filePath },
+      suggestions
+    );
+  }
+  format() {
+    const errors = this.context.details?.errors || [];
+    return `Configuration file is invalid:
+
+${errors.map((e) => `  - ${e}`).join("\n")}`;
+  }
+};
+
+// src/utils/config.ts
+import { cosmiconfigSync } from "cosmiconfig";
+import fs from "fs-extra";
+import path from "path";
+
+// src/schemas/config.ts
+import { z } from "zod";
+var FRAMEWORKS = ["react", "vue", "angular"];
+var frameworkSchema = z.enum(FRAMEWORKS, {
+  error: () => `Must be one of: ${FRAMEWORKS.join(", ")}`
+});
+var themeConfigSchema = z.object({
+  selected: z.string().min(1, "Theme name cannot be empty"),
+  palette: z.string().min(1, "Palette name cannot be empty"),
+  brandColor: z.string().min(1, "Brand color cannot be empty")
+}).strict();
+var webAwesomeConfigSchema = z.object({
+  version: z.string().optional()
+}).strict();
+var registrySourceSchema = z.object({
+  /** GitHub URL of the registry */
+  url: z.string().url("Must be a valid URL"),
+  /** Friendly name (auto-derived from repo if not set) */
+  name: z.string().optional()
+});
+var installedComponentSchema = z.object({
+  source: z.enum(["builtin", "community"]),
+  registryUrl: z.string().optional(),
+  registryVersion: z.string().optional(),
+  installedAt: z.string().optional(),
+  /** Kigumi CLI version that generated this component */
+  kigumiVersion: z.string().optional()
+});
+var installedThemeSchema = z.object({
+  source: z.enum(["builtin", "community"]),
+  registryUrl: z.string().optional(),
+  registryVersion: z.string().optional()
+});
+var kigumiConfigSchema = z.object({
+  framework: frameworkSchema,
+  typescript: z.boolean({
+    error: () => "Must be a boolean (true or false)"
+  }),
+  componentsDir: z.string().min(1, "Components directory cannot be empty"),
+  utilsDir: z.string().min(1, "Utils directory cannot be empty"),
+  stylesDir: z.string().min(1, "Styles directory cannot be empty"),
+  theme: themeConfigSchema,
+  webAwesome: webAwesomeConfigSchema.optional(),
+  /** Community registry sources */
+  registries: z.array(registrySourceSchema).optional(),
+  /** Provenance tracking for installed components */
+  installedComponents: z.record(z.string(), installedComponentSchema).optional(),
+  /** Provenance tracking for installed themes */
+  installedThemes: z.record(z.string(), installedThemeSchema).optional(),
+  /** Kigumi CLI version that initialized/last upgraded this project */
+  kigumiVersion: z.string().optional()
+}).strict();
+var DEFAULT_CONFIG = {
+  framework: "react",
+  typescript: true,
+  componentsDir: "src/components/ui",
+  utilsDir: "src/lib",
+  stylesDir: "src/styles",
+  theme: {
+    selected: "default",
+    palette: "default",
+    brandColor: "blue"
+  },
+  webAwesome: {
+    version: DEFAULT_WEBAWESOME_VERSION
+  }
+};
+var LEGACY_TOP_LEVEL_KEYS = ["aliases"];
+var LEGACY_WEB_AWESOME_KEYS = ["cdnUrl"];
+function stripLegacyKeys(raw) {
+  const cleaned = { ...raw };
+  for (const key of LEGACY_TOP_LEVEL_KEYS) {
+    delete cleaned[key];
+  }
+  if (cleaned.webAwesome && typeof cleaned.webAwesome === "object") {
+    const wa = { ...cleaned.webAwesome };
+    for (const key of LEGACY_WEB_AWESOME_KEYS) {
+      delete wa[key];
+    }
+    cleaned.webAwesome = wa;
+  }
+  return cleaned;
+}
+function mergeWithDefaults(config) {
+  const stripped = stripLegacyKeys(
+    config
+  );
+  const merged = {
+    ...DEFAULT_CONFIG,
+    ...stripped,
+    theme: {
+      ...DEFAULT_CONFIG.theme,
+      ...stripped.theme
+    },
+    webAwesome: {
+      ...DEFAULT_CONFIG.webAwesome,
+      ...stripped.webAwesome
+    }
+  };
+  const result = kigumiConfigSchema.safeParse(merged);
+  if (!result.success) {
+    const errors = result.error.issues.map((err) => {
+      const issuePath = err.path.join(".");
+      return issuePath ? `${issuePath}: ${err.message}` : err.message;
+    });
+    throw new ConfigInvalidError(errors);
+  }
+  return result.data;
+}
+
+// src/utils/config.ts
+var SEARCH_PLACES = [
+  "kigumi.config.json",
+  "kigumi-components.json",
+  "kigumi.json",
+  ".kigumirc",
+  ".kigumirc.json",
+  "package.json"
+];
+function loadConfig(cwd = process.cwd()) {
+  const explorer = cosmiconfigSync("kigumi", {
+    searchPlaces: [...SEARCH_PLACES],
+    stopDir: cwd
+  });
+  const result = explorer.search(cwd);
+  if (!result) return null;
+  return { config: result.config, filepath: result.filepath };
+}
+function getSearchPlaces() {
+  return SEARCH_PLACES;
+}
+function getConfig(cwd = process.cwd()) {
+  const loaded = loadConfig(cwd);
+  if (!loaded) {
+    throw new ConfigNotFoundError(cwd);
+  }
+  return mergeWithDefaults(loaded.config);
+}
+function mergePatch(onDisk, patch) {
+  const next = { ...onDisk, ...patch };
+  if (patch.theme) {
+    const existingTheme = onDisk.theme ?? {};
+    next.theme = { ...existingTheme, ...patch.theme };
+  }
+  if (patch.webAwesome) {
+    const existingWa = onDisk.webAwesome ?? {};
+    next.webAwesome = { ...existingWa, ...patch.webAwesome };
+  }
+  return next;
+}
+async function writePackageJsonKey(filepath, key, value) {
+  const pkg = await fs.readJson(filepath);
+  pkg[key] = value;
+  await fs.writeJson(filepath, pkg, { spaces: 2 });
+}
+async function saveConfig(patch, cwd = process.cwd()) {
+  const loaded = loadConfig(cwd);
+  if (!loaded) {
+    throw new ConfigNotFoundError(cwd);
+  }
+  const onDisk = loaded.config ?? {};
+  const next = mergePatch(onDisk, patch);
+  if (path.basename(loaded.filepath) === "package.json") {
+    await writePackageJsonKey(loaded.filepath, "kigumi", next);
+  } else {
+    await fs.writeJson(loaded.filepath, next, { spaces: 2 });
+  }
+}
+
+// src/checks/config-checks.ts
+import fs2 from "fs-extra";
+import path2 from "path";
+var ConfigExistsCheck = class {
+  id = "config-exists";
+  name = "Configuration File Exists";
+  description = "Check if a kigumi config file exists at any supported path";
+  async run(context) {
+    const loaded = loadConfig(context.cwd);
+    if (!loaded) {
+      return {
+        passed: false,
+        severity: "error" /* ERROR */,
+        message: "Configuration file not found",
+        suggestion: ["Run: kigumi init", "This will create kigumi.config.json"],
+        details: {
+          searched: [...getSearchPlaces()],
+          cwd: context.cwd
+        }
+      };
+    }
+    return {
+      passed: true,
+      severity: "info" /* INFO */,
+      message: `Configuration loaded from ${path2.basename(loaded.filepath)}`,
+      details: { filepath: loaded.filepath }
+    };
+  }
+};
+var PackageJsonExistsCheck = class {
+  id = "package-json-exists";
+  name = "Package.json Exists";
+  description = "Check if package.json exists in project";
+  async run(context) {
+    const packageJsonPath = path2.join(context.cwd, "package.json");
+    const exists = await fs2.pathExists(packageJsonPath);
+    if (!exists) {
+      return {
+        passed: false,
+        severity: "error" /* ERROR */,
+        message: "package.json not found",
+        suggestion: [
+          "Initialize npm project: npm init",
+          "Or ensure you are in the correct directory"
+        ],
+        details: {
+          path: packageJsonPath
+        }
+      };
+    }
+    return {
+      passed: true,
+      severity: "info" /* INFO */,
+      message: "package.json exists"
+    };
+  }
+};
+
+// src/checks/dependency-checks.ts
+import fs3 from "fs-extra";
+
+// src/errors/community-registry.ts
+var CommunityRegistryNotFoundError = class extends KigumiError {
+  constructor(url, cause) {
+    const suggestions = [
+      {
+        title: "Registry not found",
+        steps: [
+          `Could not find registry.json at: ${url}`,
+          "Verify the URL points to a valid GitHub repository",
+          "Check that the repository contains a registry.json file at its root",
+          "Ensure the repository is public or you have provided a GitHub token"
+        ]
+      }
+    ];
+    super(
+      504 /* REGISTRY_ERROR */,
+      `Community registry not found: ${url}`,
+      { url, error: cause?.message },
+      suggestions,
+      cause
+    );
+  }
+};
+var CommunityRegistryInvalidError = class extends KigumiError {
+  constructor(url, errors) {
+    const suggestions = [
+      {
+        title: "Registry validation failed",
+        steps: [
+          "The registry.json file has validation errors:",
+          ...errors.map((e) => `  - ${e}`),
+          'Run "kigumi registry validate" in the registry repo to fix'
+        ]
+      }
+    ];
+    super(
+      504 /* REGISTRY_ERROR */,
+      `Invalid community registry: ${url}`,
+      { url, errors },
+      suggestions
+    );
+  }
+};
+var CommunityComponentNotFoundError = class extends KigumiError {
+  constructor(componentName, registryName, available) {
+    const suggestions = [
+      {
+        title: "Component not found",
+        steps: available.length > 0 ? [
+          `Component "${componentName}" is not in registry "${registryName}"`,
+          `Available components: ${available.join(", ")}`
+        ] : [
+          `Component "${componentName}" is not in registry "${registryName}"`,
+          "This registry has no components"
+        ]
+      }
+    ];
+    super(
+      202 /* INVALID_COMPONENT */,
+      `Component "${componentName}" not found in registry "${registryName}"`,
+      { componentName, registryName, available },
+      suggestions
+    );
+  }
+};
+var FrameworkMismatchError = class extends KigumiError {
+  constructor(registryName, registryFrameworks, userFramework) {
+    const suggestions = [
+      {
+        title: "Framework mismatch",
+        steps: [
+          `Your project uses: ${userFramework}`,
+          `This registry supports: ${registryFrameworks.join(", ")}`,
+          "Look for a registry that supports your framework",
+          "OR re-run with --cross-framework to fetch the source-framework files into .kigumi/foreign/ for an agent-driven conversion"
+        ]
+      }
+    ];
+    super(
+      201 /* INVALID_FRAMEWORK */,
+      `Registry "${registryName}" does not support ${userFramework}`,
+      { registryName, registryFrameworks, userFramework },
+      suggestions
+    );
+  }
+};
+var CircularDependencyError = class extends KigumiError {
+  constructor(cycle) {
+    const cycleStr = cycle.join(" \u2192 ");
+    const suggestions = [
+      {
+        title: "Circular dependency",
+        steps: [
+          `Dependency cycle detected: ${cycleStr}`,
+          "Remove one of the dependencies to break the cycle",
+          'Run "kigumi registry validate" to check for issues'
+        ]
+      }
+    ];
+    super(
+      200 /* VALIDATION_FAILED */,
+      `Circular dependency detected: ${cycleStr}`,
+      { cycle },
+      suggestions
+    );
+  }
+};
+var PathTraversalError = class extends KigumiError {
+  constructor(filePath, registryRoot, cause) {
+    const suggestions = [
+      {
+        title: "Path traversal blocked",
+        steps: [
+          `File path "${filePath}" resolves outside the registry root`,
+          "Only paths within the registry directory are permitted"
+        ]
+      }
+    ];
+    super(
+      504 /* REGISTRY_ERROR */,
+      `Path traversal attempt: "${filePath}" escapes registry root "${registryRoot}"`,
+      { filePath, registryRoot },
+      suggestions,
+      cause
+    );
+  }
+};
+
+// src/errors/preflight.ts
+var PreFlightCheckError = class extends KigumiError {
+  constructor(checkResults) {
+    const failedChecks = checkResults.filter((r) => !r.passed);
+    const errorChecks = failedChecks.filter(
+      (r) => r.severity === "error" /* ERROR */
+    );
+    const warningChecks = failedChecks.filter(
+      (r) => r.severity === "warning" /* WARNING */
+    );
+    const suggestions = [];
+    for (const check of errorChecks) {
+      if (check.suggestion && check.suggestion.length > 0) {
+        suggestions.push({
+          title: check.message,
+          steps: check.suggestion
+        });
+      }
+    }
+    if (suggestions.length === 0) {
+      suggestions.push({
+        title: "Fix the issues and try again",
+        steps: failedChecks.map((c) => c.message)
+      });
+    }
+    super(
+      600 /* PREFLIGHT_CHECK_FAILED */,
+      "Pre-flight checks failed",
+      {
+        totalChecks: checkResults.length,
+        failedChecks: failedChecks.length,
+        errors: errorChecks.length,
+        warnings: warningChecks.length,
+        checks: failedChecks
+      },
+      suggestions
+    );
+  }
+  format() {
+    const {
+      errors: _errors,
+      warnings: _warnings,
+      checks
+    } = this.context.details || {};
+    const failedChecks = checks || [];
+    const parts = ["Pre-flight checks failed:"];
+    parts.push("");
+    const errorChecks = failedChecks.filter(
+      (c) => c.severity === "error" /* ERROR */
+    );
+    if (errorChecks.length > 0) {
+      parts.push(`Errors (${errorChecks.length}):`);
+      errorChecks.forEach((check) => {
+        parts.push(`  \u2717 ${check.message}`);
+      });
+      parts.push("");
+    }
+    const warningChecks = failedChecks.filter(
+      (c) => c.severity === "warning" /* WARNING */
+    );
+    if (warningChecks.length > 0) {
+      parts.push(`Warnings (${warningChecks.length}):`);
+      warningChecks.forEach((check) => {
+        parts.push(`  \u26A0 ${check.message}`);
+      });
+    }
+    return parts.join("\n");
+  }
+};
+
+// src/errors/validation.ts
+var ValidationError = class extends KigumiError {
+  constructor(field, value, validValues, zodError) {
+    const errorMessages = zodError?.issues.map((err) => {
+      return `${err.path.join(".")}: ${err.message}`;
+    }) || [];
+    const suggestions = [
+      {
+        title: "Provide a valid value",
+        steps: [
+          `The value "${value}" is not valid for: ${field}`,
+          ...validValues ? [
+            `Valid values: ${validValues.map((v) => JSON.stringify(v)).join(", ")}`
+          ] : [],
+          ...errorMessages.map((msg) => `Error: ${msg}`),
+          "Check the command documentation for valid options"
+        ]
+      }
+    ];
+    super(
+      200 /* VALIDATION_FAILED */,
+      `Validation failed for: ${field}`,
+      { field, value, validValues, zodErrors: errorMessages },
+      suggestions
+    );
+  }
+  format() {
+    const { field, value, validValues } = this.context.details || {};
+    const parts = [`Validation failed for: ${field}`];
+    parts.push(`  Received: ${JSON.stringify(value)}`);
+    if (validValues && Array.isArray(validValues)) {
+      parts.push(
+        `  Valid values: ${validValues.map((v) => JSON.stringify(v)).join(", ")}`
+      );
+    }
+    const zodErrors = this.context.details?.zodErrors;
+    if (zodErrors && zodErrors.length > 0) {
+      parts.push("");
+      parts.push("Validation errors:");
+      zodErrors.forEach((err) => parts.push(`  - ${err}`));
+    }
+    return parts.join("\n");
+  }
+};
+
+// src/errors/tier.ts
+var TierRestrictionError = class extends KigumiError {
+  constructor(feature, requiredTier, currentTier) {
+    const suggestions = [
+      {
+        title: "Upgrade to Pro tier",
+        steps: [
+          `"${feature}" requires Web Awesome Pro`,
+          "Visit: https://webawesome.com/pro",
+          "Sign up for a Pro account",
+          'Update your configuration: tier: "pro"',
+          "Add your Pro token to .env: WEBAWESOME_NPM_TOKEN=your-token"
+        ]
+      },
+      {
+        title: "Or use a free alternative",
+        steps: [
+          "Check available free tier features",
+          "Run: kigumi list to see all components"
+        ]
+      }
+    ];
+    super(
+      300 /* TIER_RESTRICTION */,
+      `Feature requires Pro tier: ${feature}`,
+      { feature, requiredTier, currentTier },
+      suggestions
+    );
+  }
+};
+var ProThemeRequiredError = class extends KigumiError {
+  constructor(themeName, freeThemes) {
+    const suggestions = [
+      {
+        title: "Upgrade to Pro tier",
+        steps: [
+          `Theme "${themeName}" requires Web Awesome Pro`,
+          "Visit: https://webawesome.com/pro",
+          "Sign up for a Pro account",
+          'Update kigumi.config.json: "tier": "pro"',
+          "Add your Pro token to .env: WEBAWESOME_NPM_TOKEN=your-token"
+        ]
+      },
+      {
+        title: "Or use a free theme",
+        steps: ["Free tier themes:", ...freeThemes.map((t) => `  - ${t}`)]
+      }
+    ];
+    super(
+      302 /* PRO_THEME_REQUIRED */,
+      `Theme requires Pro tier: ${themeName}`,
+      { themeName, freeThemes },
+      suggestions
+    );
+  }
+};
+
+// src/errors/layers-css.ts
+var LayersCssRewriteError = class extends KigumiError {
+  constructor(filePath, currentPackage, targetPackage, themeName) {
+    const suggestions = [
+      {
+        title: "Update the imports manually",
+        steps: [
+          `Open ${filePath}`,
+          `Replace: @import '${currentPackage}/dist/styles/webawesome.css' ...`,
+          `With:    @import '${targetPackage}/dist/styles/webawesome.css' ...`,
+          `Replace: @import '${currentPackage}/dist/styles/themes/${themeName}.css' ...`,
+          `With:    @import '${targetPackage}/dist/styles/themes/${themeName}.css' ...`,
+          "Save the file and restart your dev server"
+        ]
+      },
+      {
+        title: "Or restore the default layers.css",
+        steps: [
+          `See the reference implementation at:`,
+          `${GITHUB_REPO_URL}/blob/main/src/utils/regenerate.ts`,
+          `Look for the "generateLayersCSS" function`,
+          "Copy its template output into your layers.css",
+          "Then re-run migration"
+        ]
+      }
+    ];
+    super(
+      405 /* MIGRATION_PARSE_ERROR */,
+      `Cannot migrate layers.css automatically: expected @import pattern not found in ${filePath}`,
+      { filePath, currentPackage, targetPackage, themeName },
+      suggestions
+    );
+  }
+};
+
+// src/errors/network.ts
+var DependencyInstallError = class extends KigumiError {
+  constructor(packageName, packageManager, cause, statusCode) {
+    const isAuthError = statusCode === 401 || statusCode === 403;
+    const isNotFoundError = statusCode === 404;
+    const errorMessage = cause?.message || "";
+    const isRegistryMismatch = errorMessage.includes("ERR_PNPM_REGISTRIES_MISMATCH") || errorMessage.includes("REGISTRIES_MISMATCH");
+    const suggestions = [];
+    if (isRegistryMismatch) {
+      suggestions.push({
+        title: "Registry configuration mismatch detected",
+        steps: [
+          "Your package manager detected a registry URL change",
+          "This happens when .npmrc was updated after packages were installed",
+          `Run: rm -rf node_modules ${packageManager === "pnpm" ? "pnpm-lock.yaml" : packageManager === "yarn" ? "yarn.lock" : "package-lock.json"}`,
+          `Then run: ${packageManager} install`,
+          "This will recreate the lockfile with the new registry configuration"
+        ]
+      });
+    } else if (isAuthError) {
+      suggestions.push({
+        title: "Authentication required",
+        steps: [
+          `Failed to install ${packageName} - authentication failed`,
+          "This package requires a Pro tier token",
+          "Get your token from: https://webawesome.com/pro",
+          "Add to .env file: WEBAWESOME_NPM_TOKEN=your-token-here",
+          "The .npmrc file is already configured for you"
+        ]
+      });
+    } else if (isNotFoundError) {
+      suggestions.push({
+        title: "Package not found",
+        steps: [
+          `Package "${packageName}" not found`,
+          "Verify the package name is correct",
+          "Check if the package exists in the registry",
+          "Ensure you have access to the package"
+        ]
+      });
+    } else {
+      suggestions.push({
+        title: "Installation failed",
+        steps: [
+          `Failed to install: ${packageName}`,
+          "Check the error message above for specific details",
+          "Verify you have internet connectivity",
+          "Try running the command again"
+        ]
+      });
+      suggestions.push({
+        title: "Try manual installation",
+        steps: [
+          `Run: ${packageManager} ${packageManager === "npm" ? "install" : "add"} ${packageName}`,
+          "Check the error output for specific issues",
+          "Resolve any conflicts or version mismatches"
+        ]
+      });
+    }
+    super(
+      500 /* DEPENDENCY_INSTALL_FAILED */,
+      `Failed to install dependency: ${packageName}`,
+      { packageName, packageManager, statusCode, error: cause?.message },
+      suggestions,
+      cause
+    );
+  }
+};
+
+// src/errors/version.ts
+var VersionMismatchError = class extends KigumiError {
+  constructor(configVersion, cliVersion) {
+    super(
+      700 /* VERSION_MISMATCH */,
+      `CLI version ${cliVersion} does not match project version ${configVersion}`,
+      { configVersion, cliVersion },
+      [
+        {
+          title: "Use the matching CLI version",
+          steps: [`npx kigumi@${configVersion} add <component>`]
+        },
+        {
+          title: "Or upgrade your project to the current CLI version",
+          steps: [`npx kigumi@${cliVersion} upgrade`]
+        }
+      ]
+    );
+    this.configVersion = configVersion;
+    this.cliVersion = cliVersion;
+  }
+};
+
+// src/errors/index.ts
+function handleError(error, output) {
+  const kigumiError = error instanceof KigumiError ? error : UnknownError.from(error);
+  if (output && typeof output.error === "function") {
+    output.error(kigumiError.format(), kigumiError);
+    const suggestions = kigumiError.formatSuggestions();
+    if (suggestions) {
+      output.note("How to fix", suggestions);
+    }
+  } else {
+    console.error(kigumiError.format());
+    const suggestions = kigumiError.formatSuggestions();
+    if (suggestions) {
+      console.error("\nHow to fix:");
+      console.error(suggestions);
+    }
+  }
+  process.exit(kigumiError.exitCode);
+}
+
+// src/utils/regenerate.ts
+import fs5 from "fs-extra";
+import path4 from "path";
+
+// src/utils/detect-framework.ts
+import fs4 from "fs-extra";
+import path3 from "path";
+async function detectFramework(cwd = process.cwd()) {
+  const packageJsonPath = path3.join(cwd, "package.json");
+  if (!await fs4.pathExists(packageJsonPath)) {
+    return "unknown";
+  }
+  const packageJson = await fs4.readJson(packageJsonPath);
+  const deps = {
+    ...packageJson.dependencies,
+    ...packageJson.devDependencies
+  };
+  if (deps.react || deps["@types/react"]) {
+    return "react";
+  }
+  if (deps.vue || deps["@vue/cli-service"]) {
+    return "vue";
+  }
+  if (deps["@angular/core"]) {
+    return "angular";
+  }
+  return "unknown";
+}
+async function detectTypeScript(cwd = process.cwd()) {
+  const tsconfigPath = path3.join(cwd, "tsconfig.json");
+  const packageJsonPath = path3.join(cwd, "package.json");
+  if (await fs4.pathExists(tsconfigPath)) {
+    return true;
+  }
+  if (await fs4.pathExists(packageJsonPath)) {
+    const packageJson = await fs4.readJson(packageJsonPath);
+    const deps = {
+      ...packageJson.dependencies,
+      ...packageJson.devDependencies
+    };
+    return !!deps.typescript;
+  }
+  return false;
+}
+async function detectPackageManager(cwd = process.cwd()) {
+  if (await fs4.pathExists(path3.join(cwd, "pnpm-lock.yaml"))) {
+    return "pnpm";
+  }
+  if (await fs4.pathExists(path3.join(cwd, "yarn.lock"))) {
+    return "yarn";
+  }
+  if (await fs4.pathExists(path3.join(cwd, "bun.lockb"))) {
+    return "bun";
+  }
+  return "npm";
+}
+async function isNextProject(cwd = process.cwd()) {
+  const packageJsonPath = path3.join(cwd, "package.json");
+  if (await fs4.pathExists(packageJsonPath)) {
+    try {
+      const packageJson = await fs4.readJson(packageJsonPath);
+      const deps = {
+        ...packageJson.dependencies,
+        ...packageJson.devDependencies
+      };
+      if (deps.next) {
+        return true;
+      }
+    } catch (_error) {
+    }
+  }
+  for (const name of [
+    "next.config.js",
+    "next.config.mjs",
+    "next.config.ts",
+    "next.config.cjs"
+  ]) {
+    if (await fs4.pathExists(path3.join(cwd, name))) {
+      return true;
+    }
+  }
+  return false;
+}
+async function detectNextRouter(cwd = process.cwd()) {
+  for (const rel of ["src/app", "app"]) {
+    if (await fs4.pathExists(path3.join(cwd, rel))) {
+      return "app";
+    }
+  }
+  for (const rel of ["src/pages", "pages"]) {
+    if (await fs4.pathExists(path3.join(cwd, rel))) {
+      return "pages";
+    }
+  }
+  return "unknown";
+}
+async function detectSourceLayout(cwd = process.cwd()) {
+  const srcMarkers = [
+    "src/app",
+    "src/pages",
+    "src/main.ts",
+    "src/main.tsx",
+    "src/main.js",
+    "src/main.jsx",
+    "src/index.ts",
+    "src/index.tsx"
+  ];
+  for (const rel of srcMarkers) {
+    if (await fs4.pathExists(path3.join(cwd, rel))) {
+      return "src";
+    }
+  }
+  return "root";
+}
+async function getProjectInfo(cwd = process.cwd()) {
+  const framework = await detectFramework(cwd);
+  const typescript = await detectTypeScript(cwd);
+  const packageManager = await detectPackageManager(cwd);
+  const isNext = await isNextProject(cwd);
+  const nextRouter = isNext ? await detectNextRouter(cwd) : void 0;
+  const sourceLayout = await detectSourceLayout(cwd);
+  const packageJsonPath = path3.join(cwd, "package.json");
+  let hasVite = false;
+  if (await fs4.pathExists(packageJsonPath)) {
+    const packageJson = await fs4.readJson(packageJsonPath);
+    const deps = {
+      ...packageJson.dependencies,
+      ...packageJson.devDependencies
+    };
+    hasVite = !!deps.vite;
+  }
+  return {
+    framework,
+    typescript,
+    packageManager,
+    hasVite,
+    isNext,
+    nextRouter,
+    sourceLayout
+  };
+}
+
+// src/utils/regenerate.ts
+async function regenerateKigumiSetup(cwd, config, utilsDir, tierOverride, options, isNextOverride, nextRouterOverride) {
+  const tier = tierOverride || detectTierSync(cwd);
+  const packageName = getWebAwesomePackage(tier);
+  const stylesDir = config.stylesDir;
+  const stylesAlias = toKigumiAlias(stylesDir);
+  const isNext = isNextOverride ?? await isNextProject(cwd);
+  const nextRouter = isNext ? nextRouterOverride ?? await detectNextRouter(cwd) : void 0;
+  const skipLayersImport = nextRouter === "pages";
+  const layersPath = path4.join(cwd, stylesDir, "layers.css");
+  const layersExists = await fs5.pathExists(layersPath);
+  let layersPreserved = false;
+  if (options?.preserveLayersCSS && layersExists) {
+    layersPreserved = true;
+  } else {
+    const isCommunityTheme = config.installedThemes?.[config.theme.selected]?.source === "community";
+    const layersContent = await generateLayersCSS(
+      packageName,
+      config.theme.selected,
+      stylesDir,
+      isCommunityTheme,
+      nextRouter
+    );
+    await fs5.writeFile(layersPath, layersContent);
+  }
+  const themeClasses = config.theme.selected !== "none" ? generateThemeClassesScript(config) : "";
+  const layersImportLine = skipLayersImport ? `// Pages Router: layers.css must be imported from pages/_app.tsx
+// directly \u2014 Next forbids global CSS imports from lib/.` : `import '${stylesAlias}/layers.css';`;
+  const setupFileContent = `/**
+ * Kigumi Setup
+ *
+ * This file is auto-generated by Kigumi CLI.
+ * It imports Web Awesome styles with cascade layers and applies theme classes.
+ *
+ * Current theme: ${config.theme.selected}
+ * Current palette: ${config.theme.palette}
+ * Current brand: ${config.theme.brandColor}
+ *
+ * To change themes, use: kigumi theme <name>
+ * To change brand color, use: kigumi brand <color>
+ */
+
+// Prevent duplicate custom-element registrations when Web Awesome components
+// share internal dependencies (e.g. toast-item internally uses progress-ring)
+if (typeof customElements !== 'undefined') {
+  const _ceDefine = customElements.define.bind(customElements);
+  customElements.define = function (name: string, ctor: CustomElementConstructor, options?: ElementDefinitionOptions) {
+    if (!customElements.get(name)) _ceDefine(name, ctor, options);
+  };
+}
+
+// Import Web Awesome CSS with cascade layers for predictable specificity control
+${layersImportLine}
+${themeClasses}
+export {};
+`;
+  const finalSetupFileContent = isNext ? `'use client';
+
+${setupFileContent}` : setupFileContent;
+  const setupFilePath = path4.join(cwd, utilsDir, "kigumi.ts");
+  await fs5.writeFile(setupFilePath, finalSetupFileContent);
+  return { layersPreserved };
+}
+function generateThemeClassesScript(config) {
+  return `
+// Apply theme classes to <html> element
+if (typeof document !== 'undefined') {
+  const html = document.documentElement;
+
+  // Remove old theme classes (for hot reload)
+  html.className = html.className
+    .replace(/\\bwa-theme-\\S+/g, '')
+    .replace(/\\bwa-palette-\\S+/g, '')
+    .replace(/\\bwa-brand-\\S+/g, '');
+
+  // Add new theme classes
+  html.classList.add('wa-theme-${config.theme.selected}');
+  html.classList.add('wa-palette-${config.theme.palette}');
+  html.classList.add('wa-brand-${config.theme.brandColor}');
+}
+`;
+}
+async function generateLayersCSS(packageName, themeName, _stylesDir, isCommunityTheme = false, nextRouter) {
+  const themeImport = isCommunityTheme ? `./community-themes/${themeName}.css` : `${packageName}/dist/styles/themes/${themeName}.css`;
+  const usePlainImports = nextRouter === "pages";
+  const baseLayer = usePlainImports ? "" : " layer(base)";
+  const themeLayer = usePlainImports ? "" : " layer(theme)";
+  return `/**
+ * Web Awesome CSS Cascade Layers
+ *
+ * This file is auto-generated by Kigumi CLI.
+ * It wraps Web Awesome CSS in cascade layers for predictable specificity control.
+ *
+ * Layer hierarchy (earlier = lower priority):
+ * 1. base - Web Awesome foundation + theme styles
+ * 2. theme - Your custom CSS overrides (theme.css)
+ *
+ * Learn more: https://developer.mozilla.org/en-US/docs/Web/CSS/@layer
+ */
+
+/* Define layer order */
+@layer base, theme;
+
+/* Layer 1: Web Awesome base styles */
+@import '${packageName}/dist/styles/webawesome.css'${baseLayer};
+
+/* Layer 1: Web Awesome theme styles */
+@import '${themeImport}'${baseLayer};
+
+/* Layer 2: Your custom CSS overrides (sibling of layers.css) */
+@import './theme.css'${themeLayer};
+`;
+}
+async function surgicalRewriteLayersCss(filePath, targetPackage, themeName) {
+  const content = await fs5.readFile(filePath, "utf-8");
+  const basePattern = /@import\s+['"](@awesome\.me\/webawesome(?:-pro)?)\/dist\/styles\/webawesome\.css['"]/;
+  const basePatternGlobal = new RegExp(basePattern.source, "g");
+  const themePattern = /@import\s+['"](@awesome\.me\/webawesome(?:-pro)?)\/dist\/styles\/themes\/([a-z][a-z0-9-]*)\.css['"]/;
+  const themePatternGlobal = new RegExp(themePattern.source, "g");
+  const hasBase = basePattern.test(content);
+  const hasTheme = themePattern.test(content);
+  if (!hasBase && !hasTheme) {
+    const currentPackage = content.includes(WEB_AWESOME_PRO_PACKAGE) ? WEB_AWESOME_PRO_PACKAGE : WEB_AWESOME_FREE_PACKAGE;
+    throw new LayersCssRewriteError(
+      filePath,
+      currentPackage,
+      targetPackage,
+      themeName
+    );
+  }
+  let next = content;
+  if (hasBase) {
+    next = next.replace(
+      basePatternGlobal,
+      `@import '${targetPackage}/dist/styles/webawesome.css'`
+    );
+  }
+  if (hasTheme) {
+    next = next.replace(
+      themePatternGlobal,
+      (_match, _pkg, theme) => `@import '${targetPackage}/dist/styles/themes/${theme}.css'`
+    );
+  }
+  if (next === content) {
+    return { changed: false };
+  }
+  await fs5.writeFile(filePath, next);
+  return { changed: true };
+}
+async function generateViteEnvDts(cwd, srcDir, waPackage = WEB_AWESOME_FREE_PACKAGE) {
+  const viteEnvContent = `/// <reference types="vite/client" />
+
+/**
+ * Web Awesome JSX Types
+ *
+ * This extends React's JSX.IntrinsicElements with Web Awesome custom elements.
+ * Uses the official types from the ${waPackage} package.
+ *
+ * IMPORTANT: Uses 'declare global' to extend JSX without overwriting React module.
+ *
+ * @see https://webawesome.com/docs/#react-users
+ */
+
+import type {
+  CustomElements,
+  CustomCssProperties,
+} from '${waPackage}/dist/custom-elements-jsx.d.ts';
+
+declare global {
+  namespace JSX {
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    interface IntrinsicElements extends CustomElements {}
+  }
+}
+
+declare module 'react' {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface CSSProperties extends CustomCssProperties {}
+}
+
+export {};
+`;
+  const viteEnvPath = path4.join(cwd, srcDir, "vite-env.d.ts");
+  await fs5.writeFile(viteEnvPath, viteEnvContent);
+}
+async function generateNextEnvDts(cwd, srcDir, waPackage = WEB_AWESOME_FREE_PACKAGE) {
+  const dtsContent = `/**
+ * Web Awesome JSX Types
+ *
+ * This extends React's JSX.IntrinsicElements with Web Awesome custom elements.
+ * Uses the official types from the ${waPackage} package.
+ *
+ * IMPORTANT: Uses 'declare global' to extend JSX without overwriting React module.
+ *
+ * @see https://webawesome.com/docs/#react-users
+ */
+
+import type {
+  CustomElements,
+  CustomCssProperties,
+} from '${waPackage}/dist/custom-elements-jsx.d.ts';
+
+declare global {
+  namespace JSX {
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    interface IntrinsicElements extends CustomElements {}
+  }
+}
+
+declare module 'react' {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface CSSProperties extends CustomCssProperties {}
+}
+
+export {};
+`;
+  const dtsPath = path4.join(cwd, srcDir, "web-awesome.d.ts");
+  await fs5.writeFile(dtsPath, dtsContent);
+}
+async function generateThemeCSS() {
+  return `/**
+ * Web Awesome Theme Customization
+ *
+ * This file is for your custom CSS overrides.
+ * Web Awesome base and theme imports are handled in layers.css.
+ *
+ * This file is imported into the 'theme' cascade layer,
+ * which has higher priority than Web Awesome base styles.
+ * This means your customizations will always override Web Awesome defaults.
+ *
+ * Learn more:
+ *   Customizing: https://webawesome.com/docs/customizing
+ *   Design Tokens: https://webawesome.com/docs/tokens
+ *   CSS Cascade Layers: https://developer.mozilla.org/en-US/docs/Web/CSS/@layer
+ */
+
+:root {
+  /* Your custom CSS variable overrides here */
+  /* Example: --wa-color-brand-60: #6366f1; */
+}
+`;
+}
+async function generateGitIgnore(cwd) {
+  const gitignorePath = path4.join(cwd, ".gitignore");
+  const exists = await fs5.pathExists(gitignorePath);
+  const essentialEntries = [
+    "# Dependencies",
+    "node_modules/",
+    "",
+    "# Environment variables",
+    ".env",
+    ".env.local",
+    ".env.*.local",
+    "",
+    "# Build outputs",
+    "dist/",
+    "build/",
+    "",
+    "# Kigumi cross-framework staging (transient cache for agent conversion)",
+    ".kigumi/foreign/",
+    "",
+    "# Kigumi registry cache (transient)",
+    ".kigumi/cache/"
+  ];
+  if (!exists) {
+    const content2 = essentialEntries.join("\n") + "\n";
+    await fs5.writeFile(gitignorePath, content2);
+    return;
+  }
+  let content = await fs5.readFile(gitignorePath, "utf-8");
+  if (!content.includes(".env")) {
+    content += "\n# Environment variables\n.env\n.env.local\n.env.*.local\n";
+  }
+  if (!/^\.kigumi\/foreign\/$/m.test(content)) {
+    if (!content.endsWith("\n")) {
+      content += "\n";
+    }
+    content += "\n# Kigumi cross-framework staging (transient cache for agent conversion)\n.kigumi/foreign/\n";
+  }
+  if (!/^\.kigumi\/cache\/$/m.test(content)) {
+    if (!content.endsWith("\n")) {
+      content += "\n";
+    }
+    content += "\n# Kigumi registry cache (transient)\n.kigumi/cache/\n";
+  }
+  await fs5.writeFile(gitignorePath, content);
+}
+
+// src/utils/github-fetcher.ts
+import os from "os";
+import path5 from "path";
+import fs6 from "fs-extra";
+
+// src/schemas/community-registry.ts
+import semver from "semver";
+import { z as z2 } from "zod";
+var safePathSchema = z2.string().min(1).refine(
+  (value) => {
+    if (value.startsWith("/")) return false;
+    if (value.includes("\\")) return false;
+    return value.split("/").every(
+      (segment) => segment !== ".." && segment !== "." && segment !== ""
+    );
+  },
+  {
+    message: "Path may not be absolute, contain '.', '..', empty segments, or backslashes"
+  }
+);
+var componentFilesSchema = z2.object({
+  /** Path to main component file, relative to registry root */
+  component: safePathSchema,
+  /** Path to CSS file */
+  css: safePathSchema.optional(),
+  /** Path to test file */
+  test: safePathSchema.optional(),
+  /** Additional files (utils, hooks, types) */
+  extras: z2.array(safePathSchema).default([])
+});
+var communityComponentSchema = z2.object({
+  name: z2.string().min(1),
+  description: z2.string().optional(),
+  category: z2.string().optional(),
+  /** Keys of other components in this registry that this component depends on */
+  dependencies: z2.array(z2.string()).default([]),
+  /** Framework-specific file paths (keyed by framework name) */
+  files: z2.record(z2.string(), componentFilesSchema).refine(
+    (files) => {
+      const validFrameworks = ["react", "vue", "angular"];
+      return Object.keys(files).every((k) => validFrameworks.includes(k));
+    },
+    {
+      message: "File keys must be valid framework names (react, vue, angular)"
+    }
+  ),
+  /** npm packages this component needs (not Web Awesome packages) */
+  peerDependencies: z2.record(z2.string(), z2.string()).optional()
+});
+var communityThemeSchema = z2.object({
+  name: z2.string().min(1),
+  description: z2.string().optional(),
+  /** URL to a preview screenshot */
+  preview: z2.string().url().optional(),
+  /** Theme files */
+  files: z2.object({
+    /** Main theme CSS file */
+    css: z2.string().min(1),
+    /** Optional CSS variables file */
+    variables: z2.string().optional()
+  }),
+  /** Built-in theme this extends */
+  extends: z2.string().optional()
+});
+var communityRegistrySchema = z2.object({
+  /** JSON Schema URL for editor support */
+  $schema: z2.string().optional(),
+  /** Registry name */
+  name: z2.string().min(1),
+  /** Registry description */
+  description: z2.string().optional(),
+  /** Author name or handle */
+  author: z2.string().optional(),
+  /** License identifier */
+  license: z2.string().optional(),
+  /** Homepage URL */
+  homepage: z2.string().url().optional(),
+  /** Semver version (no ranges); pre-release and build metadata permitted */
+  version: z2.string().refine((value) => semver.valid(value) !== null, {
+    message: "Must be a valid semver version (e.g., 1.0.0 or 1.0.0-beta.1)"
+  }),
+  /** Frameworks this registry provides components for */
+  frameworks: z2.array(frameworkSchema).min(1),
+  /** Minimum Kigumi CLI version required (semver, no ranges) */
+  kigumiVersion: z2.string().refine((value) => semver.valid(value) !== null, {
+    message: "kigumiVersion must be a valid semver string (e.g., 0.19.0 or 1.0.0-beta.1)"
+  }).optional(),
+  /** Component definitions keyed by slug */
+  components: z2.record(z2.string(), communityComponentSchema).optional().default({}),
+  /** Theme definitions keyed by slug */
+  themes: z2.record(z2.string(), communityThemeSchema).optional().default({})
+});
+function validateCommunityRegistry(data, url) {
+  const result = communityRegistrySchema.safeParse(data);
+  if (!result.success) {
+    const errors = result.error.issues.map((issue) => {
+      const path6 = issue.path.join(".");
+      return path6 ? `${path6}: ${issue.message}` : issue.message;
+    });
+    throw new CommunityRegistryInvalidError(url, errors);
+  }
+  return result.data;
+}
+function validateRegistryDependencies(registry) {
+  const errors = [];
+  const componentKeys = new Set(Object.keys(registry.components));
+  for (const [key, component] of Object.entries(registry.components)) {
+    for (const dep of component.dependencies) {
+      if (!componentKeys.has(dep)) {
+        errors.push(
+          `Component "${key}" depends on "${dep}" which is not defined in this registry`
+        );
+      }
+    }
+  }
+  return errors;
+}
+
+// src/utils/version-check.ts
+import semver2 from "semver";
+function parseSemver(version) {
+  const match = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return {
+    major: parseInt(match[1], 10),
+    minor: parseInt(match[2], 10),
+    patch: parseInt(match[3], 10)
+  };
+}
+function checkVersionCompatibility(configVersion, cliVersion) {
+  if (!configVersion) {
+    return { status: "no-pin" };
+  }
+  const parsedConfig = parseSemver(configVersion);
+  const parsedCli = parseSemver(cliVersion);
+  if (!parsedConfig || !parsedCli) {
+    return { status: "match" };
+  }
+  if (parsedConfig.major !== parsedCli.major) {
+    return {
+      status: "major-mismatch",
+      configVersion,
+      cliVersion
+    };
+  }
+  if (parsedConfig.minor !== parsedCli.minor) {
+    return {
+      status: "minor-mismatch",
+      configVersion,
+      cliVersion
+    };
+  }
+  return { status: "match" };
+}
+function satisfiesMinimum(version, minimum) {
+  if (!semver2.valid(version) || !semver2.valid(minimum)) return false;
+  return semver2.satisfies(version, `>=${minimum}`, { includePrerelease: true });
+}
+
+// src/utils/github-fetcher.ts
+function isLocalPathInput(input) {
+  const trimmed = input.trim();
+  return trimmed.startsWith("./") || trimmed.startsWith("../") || trimmed.startsWith("/") || trimmed === "." || trimmed === ".." || trimmed.startsWith("~/") || trimmed === "~";
+}
+function resolveLocalPath(input, baseDir) {
+  const trimmed = input.trim();
+  if (trimmed === "~" || trimmed.startsWith("~/")) {
+    const rest = trimmed === "~" ? "" : trimmed.slice(2);
+    return path5.join(os.homedir(), rest);
+  }
+  if (path5.isAbsolute(trimmed)) {
+    return trimmed;
+  }
+  return path5.resolve(baseDir ?? process.cwd(), trimmed);
+}
+function parseRegistrySource(input, options) {
+  if (isLocalPathInput(input)) {
+    const absolutePath = resolveLocalPath(input, options?.baseDir);
+    return {
+      kind: "local",
+      url: absolutePath,
+      absolutePath
+    };
+  }
+  return parseGitHubUrl(input);
+}
+function parseGitHubUrl(url) {
+  let normalized = url.trim();
+  if (!normalized.startsWith("http")) {
+    normalized = `https://${normalized}`;
+  }
+  normalized = normalized.replace(/\/+$/, "");
+  let parsed;
+  try {
+    parsed = new URL(normalized);
+  } catch (error) {
+    throw new Error(`Invalid URL: ${url}`, { cause: error });
+  }
+  if (parsed.hostname !== "github.com") {
+    throw new Error(`Only GitHub URLs are supported. Got: ${parsed.hostname}`);
+  }
+  const pathParts = parsed.pathname.split("/").filter(Boolean);
+  if (pathParts.length < 2) {
+    throw new Error(
+      `Invalid GitHub repository URL: ${url}. Expected format: https://github.com/owner/repo`
+    );
+  }
+  const owner = pathParts[0];
+  const repo = pathParts[1];
+  let branch = "main";
+  if (pathParts.length >= 4 && pathParts[2] === "tree") {
+    branch = pathParts.slice(3).join("/");
+  }
+  return {
+    kind: "github",
+    url: `https://github.com/${owner}/${repo}`,
+    owner,
+    repo,
+    branch
+  };
+}
+function buildRawUrl(source, filePath) {
+  const cleanPath = filePath.replace(/^\//, "");
+  return `${GITHUB_RAW_BASE_URL}/${source.owner}/${source.repo}/${source.branch}/${cleanPath}`;
+}
+async function fetchFile(source, filePath) {
+  if (source.kind === "local") {
+    const cleanPath = filePath.replace(/^\//, "");
+    const absoluteFilePath = path5.resolve(source.absolutePath, cleanPath);
+    if (absoluteFilePath !== source.absolutePath && !absoluteFilePath.startsWith(source.absolutePath + path5.sep)) {
+      throw new PathTraversalError(filePath, source.absolutePath);
+    }
+    try {
+      return await fs6.readFile(absoluteFilePath, "utf-8");
+    } catch (error) {
+      const errno = error;
+      if (errno.code === "ENOENT") {
+        throw new Error(
+          `File not found: ${filePath} in ${source.absolutePath}`,
+          { cause: error }
+        );
+      }
+      throw new Error(
+        `Failed to read ${filePath} from ${source.absolutePath}: ${errno.message}`,
+        { cause: error }
+      );
+    }
+  }
+  const url = buildRawUrl(source, filePath);
+  const headers = {
+    "User-Agent": "kigumi-cli"
+  };
+  if (source.token) {
+    headers["Authorization"] = `token ${source.token}`;
+  }
+  const response = await fetch(url, { headers });
+  if (!response.ok) {
+    if (response.status === 404) {
+      throw new Error(`File not found: ${filePath} in ${source.url}`);
+    }
+    if (response.status === 401 || response.status === 403) {
+      throw new Error(
+        `Authentication failed for ${source.url}. Provide a GitHub token for private repositories.`
+      );
+    }
+    throw new Error(
+      `Failed to fetch ${filePath} from ${source.url}: ${response.status} ${response.statusText}`
+    );
+  }
+  return response.text();
+}
+async function fetchRegistryJson(source, output) {
+  const content = await fetchFile(source, "registry.json");
+  let data;
+  try {
+    data = JSON.parse(content);
+  } catch (error) {
+    throw new Error(`Invalid JSON in registry.json from ${source.url}`, {
+      cause: error
+    });
+  }
+  const registry = validateCommunityRegistry(data, source.url);
+  if (registry.kigumiVersion && output) {
+    if (!satisfiesMinimum(CLI_VERSION, registry.kigumiVersion)) {
+      output.warn(
+        `Registry "${registry.name}" requires kigumi >= ${registry.kigumiVersion}, you have ${CLI_VERSION}. Some features may not work correctly.`
+      );
+    }
+  }
+  return registry;
+}
+
+// src/utils/github-token.ts
+import { execa } from "execa";
+async function getGitHubToken() {
+  const githubToken = process.env.GITHUB_TOKEN;
+  if (githubToken?.trim()) {
+    return githubToken.trim();
+  }
+  const kigumiToken = process.env.KIGUMI_GITHUB_TOKEN;
+  if (kigumiToken?.trim()) {
+    return kigumiToken.trim();
+  }
+  try {
+    const { stdout } = await execa("gh", ["auth", "token"]);
+    const token = stdout.trim();
+    if (token) {
+      return token;
+    }
+  } catch (_error) {
+  }
+  return void 0;
+}
+
+// src/utils/registry-resolver.ts
+function resolveRegistrySource(from, config) {
+  if (from.includes("/") || from.includes(".")) {
+    return from;
+  }
+  const registries = config.registries || [];
+  const match = registries.find(
+    (r) => r.name?.toLowerCase() === from.toLowerCase()
+  );
+  if (!match) {
+    const available = registries.map((r) => r.name).filter(Boolean).join(", ");
+    throw new Error(
+      `Registry "${from}" not found.` + (available ? ` Connected registries: ${available}` : ' Run "kigumi registry connect <url>" to connect one.')
+    );
+  }
+  return match.url;
+}
+
+export {
+  confirm,
+  select,
+  text,
+  multiselect,
+  isCancel,
+  getOutput2 as getOutput,
+  CheckRunner,
+  UserCancelledError,
+  ConfigNotFoundError,
+  ConfigInvalidError,
+  FRAMEWORKS,
+  frameworkSchema,
+  kigumiConfigSchema,
+  DEFAULT_CONFIG,
+  loadConfig,
+  getConfig,
+  saveConfig,
+  ConfigExistsCheck,
+  PackageJsonExistsCheck,
+  ValidationError,
+  TierRestrictionError,
+  ProThemeRequiredError,
+  LayersCssRewriteError,
+  DependencyInstallError,
+  CommunityRegistryNotFoundError,
+  CommunityComponentNotFoundError,
+  FrameworkMismatchError,
+  CircularDependencyError,
+  PreFlightCheckError,
+  VersionMismatchError,
+  handleError,
+  communityRegistrySchema,
+  validateRegistryDependencies,
+  isNextProject,
+  detectNextRouter,
+  getProjectInfo,
+  regenerateKigumiSetup,
+  surgicalRewriteLayersCss,
+  generateViteEnvDts,
+  generateNextEnvDts,
+  generateThemeCSS,
+  generateGitIgnore,
+  checkVersionCompatibility,
+  parseRegistrySource,
+  parseGitHubUrl,
+  fetchFile,
+  fetchRegistryJson,
+  getGitHubToken,
+  resolveRegistrySource
+};
+//# sourceMappingURL=chunk-L52LAS37.js.map