@foxlight/cli 0.1.0

package/README.md

@@ -0,0 +1,90 @@
+# @foxlight/cli
+
+Command-line interface for [Foxlight](https://github.com/josegabrielcruz/foxlight) — the open-source front-end intelligence platform.
+
+## Installation
+
+```bash
+npm install -g @foxlight/cli
+```
+
+Or use via npx:
+
+```bash
+npx @foxlight/cli <command>
+```
+
+## Commands
+
+### `foxlight init`
+
+Initialize Foxlight in your project. Creates a `.foxlight.json` configuration file.
+
+```bash
+foxlight init
+```
+
+### `foxlight analyze`
+
+Scan your project and discover components, imports, and dependencies.
+
+```bash
+foxlight analyze
+foxlight analyze --json           # Output as JSON
+foxlight analyze --root ./my-app  # Specify project root
+```
+
+### `foxlight health`
+
+Show the component health dashboard with scores for bundle size, test coverage, accessibility, freshness, and performance.
+
+```bash
+foxlight health
+foxlight health --component Button  # Filter to one component
+foxlight health --json              # Output as JSON
+```
+
+### `foxlight cost`
+
+Estimate hosting costs based on your bundle sizes across different providers.
+
+```bash
+foxlight cost
+foxlight cost --provider vercel     # Specific provider
+foxlight cost --json                # Output as JSON
+```
+
+### `foxlight upgrade <package>`
+
+Analyze the impact of upgrading a dependency.
+
+```bash
+foxlight upgrade react
+foxlight upgrade react --to 19.0.0  # Target specific version
+foxlight upgrade --json              # Output as JSON
+```
+
+## Global Options
+
+| Option         | Description                           |
+| -------------- | ------------------------------------- |
+| `--root <dir>` | Project root directory (default: `.`) |
+| `--json`       | Output results as JSON                |
+| `--help`       | Show help message                     |
+| `--version`    | Show version number                   |
+
+## Configuration
+
+Create a `.foxlight.json` in your project root:
+
+```json
+{
+  "include": ["src/**/*.{ts,tsx,js,jsx,vue,svelte}"],
+  "exclude": ["**/*.test.*", "**/*.spec.*"],
+  "framework": "react"
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,857 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { resolve as resolve4 } from "path";
+
+// src/commands/analyze.ts
+import { analyzeProject } from "@foxlight/analyzer";
+
+// src/utils/output.ts
+var COLORS = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  magenta: "\x1B[35m",
+  cyan: "\x1B[36m",
+  gray: "\x1B[90m"
+};
+function color(text, ...codes) {
+  const prefix = codes.map((c) => COLORS[c]).join("");
+  return `${prefix}${text}${COLORS.reset}`;
+}
+var ui = {
+  /** Print the Foxlight banner / header. */
+  banner() {
+    console.log("");
+    console.log(color("  \u{1F98A} Foxlight", "bold", "cyan"));
+    console.log(color("  Front-End Intelligence Platform", "dim"));
+    console.log("");
+  },
+  /** Print a section header. */
+  heading(text) {
+    console.log(color(`
+  ${text}`, "bold"));
+    console.log(color("  " + "\u2500".repeat(48), "dim"));
+  },
+  /** Print an info line. */
+  info(label, value) {
+    console.log(`  ${color(label, "dim")} ${value}`);
+  },
+  /** Print a success message. */
+  success(text) {
+    console.log(`  ${color("\u2713", "green")} ${text}`);
+  },
+  /** Print a warning message. */
+  warn(text) {
+    console.log(`  ${color("\u26A0", "yellow")} ${text}`);
+  },
+  /** Print an error message. */
+  error(text) {
+    console.log(`  ${color("\u2717", "red")} ${text}`);
+  },
+  /** Print a table row. */
+  row(columns, widths) {
+    const formatted = columns.map((col, i) => col.padEnd(widths[i] ?? 20));
+    console.log(`  ${formatted.join("  ")}`);
+  },
+  /** Print a table header. */
+  tableHeader(columns, widths) {
+    const formatted = columns.map((col, i) => color(col.padEnd(widths[i] ?? 20), "dim", "bold"));
+    console.log(`  ${formatted.join("  ")}`);
+  },
+  /** Print a component health score with color coding. */
+  healthScore(score) {
+    if (score >= 80) return color(`${score}`, "green", "bold");
+    if (score >= 50) return color(`${score}`, "yellow", "bold");
+    return color(`${score}`, "red", "bold");
+  },
+  /** Print a size delta with color. */
+  sizeDelta(delta) {
+    if (delta > 0) return color(`+${delta}`, "red");
+    if (delta < 0) return color(`${delta}`, "green");
+    return color("0", "dim");
+  },
+  /** Print a spinner/progress message. */
+  progress(text) {
+    process.stdout.write(`  ${color("\u25CC", "cyan")} ${text}...`);
+  },
+  /** Clear the progress line and replace with a result. */
+  progressDone(text) {
+    process.stdout.write(`\r  ${color("\u25CF", "cyan")} ${text}
+`);
+  },
+  /** Blank line. */
+  gap() {
+    console.log("");
+  }
+};
+
+// src/commands/analyze.ts
+async function runAnalyze(options) {
+  const { rootDir, json } = options;
+  ui.progress("Scanning project");
+  const result = await analyzeProject(rootDir);
+  ui.progressDone(
+    `Scanned ${result.stats.filesScanned} files in ${result.stats.duration.toFixed(0)}ms`
+  );
+  if (json) {
+    const snapshot = result.registry.createSnapshot("local", "local");
+    console.log(JSON.stringify(snapshot, null, 2));
+    return;
+  }
+  ui.heading("Analysis Results");
+  ui.info("Files scanned:", String(result.stats.filesScanned));
+  ui.info("Components found:", String(result.stats.componentsFound));
+  ui.info("Imports tracked:", String(result.stats.importsTracked));
+  ui.info("Framework:", result.config.framework ?? "auto-detected");
+  const components = result.registry.getAllComponents();
+  if (components.length > 0) {
+    ui.heading("Components");
+    const widths = [30, 12, 10, 8];
+    ui.tableHeader(["Name", "Framework", "Props", "Children"], widths);
+    for (const comp of components) {
+      ui.row(
+        [comp.name, comp.framework, String(comp.props.length), String(comp.children.length)],
+        widths
+      );
+    }
+  }
+  const cycles = result.graph.detectCycles();
+  if (cycles.length > 0) {
+    ui.heading("Circular Dependencies");
+    ui.warn(`Found ${cycles.length} circular dependency chain(s)`);
+    for (const cycle of cycles.slice(0, 5)) {
+      ui.info("  Cycle:", cycle.join(" \u2192 "));
+    }
+  }
+  const roots = result.registry.getRootComponents();
+  if (roots.length > 0) {
+    ui.heading("Top-Level Components (no parents)");
+    for (const root of roots) {
+      const subtree = result.registry.getSubtree(root.id);
+      ui.info(`  ${root.name}`, `(${subtree.length} components in subtree)`);
+    }
+  }
+  ui.gap();
+}
+
+// src/commands/health.ts
+import { analyzeProject as analyzeProject2 } from "@foxlight/analyzer";
+import { computeComponentHealth } from "@foxlight/core";
+async function runHealth(options) {
+  const { rootDir, json, component } = options;
+  ui.progress("Analyzing project health");
+  const result = await analyzeProject2(rootDir);
+  ui.progressDone("Analysis complete");
+  const components = result.registry.getAllComponents();
+  if (components.length === 0) {
+    ui.warn("No components found. Run `foxlight analyze` to check your config.");
+    return;
+  }
+  const healthResults = components.map((comp) => {
+    const bundleInfo = result.registry.getBundleInfo(comp.id);
+    const input = {
+      component: comp,
+      bundleInfo: bundleInfo ?? void 0
+      // Test coverage, accessibility, freshness, performance, and reliability
+      // require external data sources. They will show as "not available"
+      // until integrations are configured.
+    };
+    return computeComponentHealth(input);
+  });
+  if (json) {
+    console.log(JSON.stringify(healthResults, null, 2));
+    return;
+  }
+  const display = component ? healthResults.filter((h) => {
+    const comp = result.registry.getComponent(h.componentId);
+    return comp?.name.toLowerCase() === component.toLowerCase() || h.componentId.toLowerCase().includes(component.toLowerCase());
+  }) : healthResults;
+  if (display.length === 0) {
+    ui.error(`Component "${component}" not found.`);
+    return;
+  }
+  ui.heading("Component Health Dashboard");
+  const widths = [22, 8, 10, 10, 10, 10, 10];
+  ui.tableHeader(["Component", "Score", "Bundle", "Tests", "A11y", "Fresh", "Perf"], widths);
+  const sorted = [...display].sort((a, b) => a.score - b.score);
+  for (const h of sorted) {
+    const comp = result.registry.getComponent(h.componentId);
+    const name = comp?.name ?? h.componentId;
+    ui.row(
+      [
+        name,
+        ui.healthScore(h.score),
+        ui.healthScore(h.metrics.bundleSize.score),
+        ui.healthScore(h.metrics.testCoverage.score),
+        ui.healthScore(h.metrics.accessibility.score),
+        ui.healthScore(h.metrics.freshness.score),
+        ui.healthScore(h.metrics.performance.score)
+      ],
+      widths
+    );
+  }
+  const avgScore = display.reduce((sum, h) => sum + h.score, 0) / display.length;
+  const critical = display.filter((h) => h.score < 50).length;
+  const warning = display.filter((h) => h.score >= 50 && h.score < 80).length;
+  const healthy = display.filter((h) => h.score >= 80).length;
+  ui.heading("Summary");
+  ui.info("Average health score:", ui.healthScore(Math.round(avgScore)));
+  ui.success(`${healthy} healthy`);
+  if (warning > 0) ui.warn(`${warning} need attention`);
+  if (critical > 0) ui.error(`${critical} critical`);
+  ui.gap();
+  ui.info("Tip:", "Integrate test coverage, accessibility, and performance data for full scoring.");
+  ui.gap();
+}
+
+// src/commands/init.ts
+import { existsSync } from "fs";
+import { writeFile } from "fs/promises";
+import { join } from "path";
+import { detectFramework } from "@foxlight/core";
+async function runInit(options) {
+  const { rootDir } = options;
+  const configPath = join(rootDir, "foxlight.config.ts");
+  if (existsSync(configPath)) {
+    ui.warn("foxlight.config.ts already exists. Skipping initialization.");
+    return;
+  }
+  ui.progress("Detecting project settings");
+  const framework = await detectFramework(rootDir);
+  ui.progressDone(`Detected framework: ${framework}`);
+  const configContent = generateConfig(framework);
+  await writeFile(configPath, configContent, "utf-8");
+  ui.success(`Created ${configPath}`);
+  ui.gap();
+  ui.info("Next steps:", "");
+  ui.info("  1.", "Review foxlight.config.ts and adjust settings");
+  ui.info("  2.", "Run `foxlight analyze` to scan your project");
+  ui.info("  3.", "Run `foxlight health` to see component health scores");
+  ui.gap();
+}
+function generateConfig(framework) {
+  return `import type { FoxlightConfig } from "@foxlight/core";
+
+const config: FoxlightConfig = {
+  rootDir: ".",
+
+  // Source files to analyze
+  include: [
+    "src/**/*.{tsx,jsx,vue,svelte}",
+    "components/**/*.{tsx,jsx,vue,svelte}",
+    "app/**/*.{tsx,jsx,vue,svelte}",
+  ],
+
+  // Files to exclude
+  exclude: [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/*.stories.*",
+  ],
+
+  // Auto-detected framework: "${framework}"
+  // Uncomment to override:
+  // framework: "${framework}",
+
+  // Cost model (uncomment and configure for cost analysis)
+  // costModel: {
+  //   provider: "vercel",
+  //   invocationCostPer1M: 0.60,
+  //   bandwidthCostPerGB: 0.15,
+  //   storageCostPerGB: 0.023,
+  //   baseCost: 0,
+  // },
+
+  // Baseline storage for visual regression (uncomment to configure)
+  // baselines: {
+  //   provider: "s3",
+  //   bucket: "my-foxlight-baselines",
+  //   prefix: "visual",
+  // },
+};
+
+export default config;
+`;
+}
+
+// src/commands/cost.ts
+import { analyzeProject as analyzeProject3 } from "@foxlight/analyzer";
+import {
+  estimateMonthlyCost,
+  COST_MODELS,
+  DEFAULT_TRAFFIC
+} from "@foxlight/core";
+import { formatBytes } from "@foxlight/bundle";
+async function runCost(options) {
+  const { rootDir, json, provider, pageViews } = options;
+  ui.progress("Analyzing project for cost estimation");
+  const result = await analyzeProject3(rootDir);
+  ui.progressDone("Analysis complete");
+  const components = result.registry.getAllComponents();
+  if (components.length === 0) {
+    ui.warn("No components found. Run `foxlight analyze` to check your config.");
+    return;
+  }
+  const bundleInfos = components.map((comp) => result.registry.getBundleInfo(comp.id)).filter((info) => info !== void 0);
+  const hasBundleData = bundleInfos.length > 0;
+  const traffic = {
+    ...DEFAULT_TRAFFIC,
+    ...pageViews ? { monthlyPageViews: pageViews } : {}
+  };
+  const providers = provider ? { [provider]: COST_MODELS[provider] } : COST_MODELS;
+  if (provider && !COST_MODELS[provider]) {
+    ui.error(`Unknown provider: ${provider}`);
+    ui.info("Available providers:", Object.keys(COST_MODELS).join(", "));
+    return;
+  }
+  const estimates = {};
+  for (const [name, model] of Object.entries(providers)) {
+    if (!model) continue;
+    estimates[name] = estimateMonthlyCost(bundleInfos, model, traffic);
+  }
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          components: components.length,
+          hasBundleData,
+          traffic,
+          estimates
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  ui.heading("Cost Estimation");
+  ui.info("Components:", String(components.length));
+  ui.info(
+    "Bundle data:",
+    hasBundleData ? "available" : "not yet available \u2014 run a build with the Foxlight plugin first"
+  );
+  ui.info("Traffic assumption:", `${formatNumber(traffic.monthlyPageViews)} page views/month`);
+  if (bundleInfos.length > 0) {
+    const totalRaw = bundleInfos.reduce((sum, b) => sum + b.selfSize.raw, 0);
+    const totalGzip = bundleInfos.reduce((sum, b) => sum + b.selfSize.gzip, 0);
+    ui.info("Total bundle size:", `${formatBytes(totalRaw)} (${formatBytes(totalGzip)} gzip)`);
+  }
+  ui.heading("Estimated Monthly Cost by Provider");
+  const widths = [16, 14];
+  ui.tableHeader(["Provider", "Monthly Cost"], widths);
+  for (const [name, cost] of Object.entries(estimates)) {
+    ui.row([capitalize(name), formatCurrency(cost)], widths);
+  }
+  ui.gap();
+  ui.info(
+    "Note:",
+    "Estimates are based on bundle size and traffic assumptions. Actual costs vary."
+  );
+  ui.gap();
+}
+function formatCurrency(amount) {
+  if (amount < 0.01) return "< $0.01";
+  return `$${amount.toFixed(2)}`;
+}
+function formatNumber(n) {
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(0)}K`;
+  return String(Math.round(n));
+}
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+// src/commands/upgrade.ts
+import { analyzeProject as analyzeProject4 } from "@foxlight/analyzer";
+import { analyzeUpgrade } from "@foxlight/core";
+async function runUpgrade(options) {
+  const { rootDir, packageName, targetVersion, json } = options;
+  ui.progress(`Analyzing upgrade impact for ${packageName}`);
+  const result = await analyzeProject4(rootDir);
+  ui.progressDone("Analysis complete");
+  const components = result.registry.getAllComponents();
+  const affectedComponents = components.filter((c) => c.dependencies.includes(packageName));
+  ui.progress(`Checking ${packageName} upgrade`);
+  const preview = await analyzeUpgrade({
+    rootDir,
+    packageName,
+    targetVersion,
+    affectedComponents
+  });
+  ui.progressDone("Upgrade analysis complete");
+  if (json) {
+    console.log(JSON.stringify(preview, null, 2));
+    return;
+  }
+  ui.heading(`Upgrade Preview: ${packageName}`);
+  ui.info("Current version:", preview.fromVersion);
+  ui.info("Target version:", preview.toVersion);
+  ui.info("Risk level:", formatRisk(preview.risk));
+  ui.heading("Checks");
+  for (const check of preview.checks) {
+    const icon = check.status === "pass" ? "\u2713" : check.status === "warn" ? "\u26A0" : "\u2717";
+    const colorFn = check.status === "pass" ? ui.success : check.status === "warn" ? ui.warn : ui.error;
+    colorFn(`${icon} ${check.name}: ${check.summary}`);
+    if (check.details) {
+      ui.info("  ", check.details);
+    }
+  }
+  if (affectedComponents.length > 0) {
+    ui.heading("Affected Components");
+    for (const comp of affectedComponents.slice(0, 20)) {
+      ui.info("  \u2022", comp.name);
+    }
+    if (affectedComponents.length > 20) {
+      ui.info("  ", `...and ${affectedComponents.length - 20} more`);
+    }
+  }
+  ui.gap();
+}
+function formatRisk(risk) {
+  switch (risk) {
+    case "low":
+      return "\u{1F7E2} Low";
+    case "medium":
+      return "\u{1F7E1} Medium";
+    case "high":
+      return "\u{1F534} High";
+  }
+}
+
+// src/commands/ci.ts
+import {
+  compareSnapshots,
+  hasSignificantChanges,
+  postPRComment,
+  createCheckRun,
+  detectGitHubEnv,
+  postMRComment,
+  detectGitLabEnv
+} from "@foxlight/ci";
+async function runCI(options) {
+  const { rootDir, json } = options;
+  const basePath = options.basePath ?? ".foxlight/snapshot.json";
+  const outputPath = options.outputPath ?? ".foxlight/snapshot.json";
+  const commitSha = process.env["GITHUB_SHA"] ?? process.env["CI_COMMIT_SHA"] ?? "local";
+  const branch = process.env["GITHUB_HEAD_REF"] ?? process.env["CI_COMMIT_BRANCH"] ?? process.env["CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"] ?? "unknown";
+  ui.progress("Analyzing project");
+  const comparison = await compareSnapshots({
+    rootDir,
+    basePath,
+    outputPath,
+    commitSha,
+    branch
+  });
+  ui.progressDone("Analysis complete");
+  const { diff, head } = comparison;
+  const significant = hasSignificantChanges(diff);
+  if (json) {
+    console.log(JSON.stringify({ diff, significant }, null, 2));
+    return;
+  }
+  ui.heading("CI Analysis Summary");
+  ui.info("Commit:", commitSha.slice(0, 8));
+  ui.info("Branch:", branch);
+  ui.info("Components:", String(head.components.length));
+  ui.info("Significant changes:", significant ? "yes" : "no");
+  if (diff.components.added.length > 0) {
+    ui.success(`${diff.components.added.length} component(s) added`);
+  }
+  if (diff.components.removed.length > 0) {
+    ui.warn(`${diff.components.removed.length} component(s) removed`);
+  }
+  if (diff.components.modified.length > 0) {
+    ui.info("Modified:", `${diff.components.modified.length} component(s)`);
+  }
+  const githubEnv = detectGitHubEnv();
+  if (githubEnv.token && githubEnv.owner && githubEnv.repo && githubEnv.prNumber) {
+    ui.progress("Posting GitHub PR comment");
+    try {
+      const config = githubEnv;
+      await postPRComment(config, diff);
+      ui.progressDone("PR comment posted");
+      await createCheckRun(config, diff, {
+        name: "Foxlight Analysis",
+        headSha: commitSha
+      });
+      ui.success("Check run created");
+    } catch (err) {
+      ui.warn(`GitHub integration failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  const gitlabEnv = detectGitLabEnv();
+  const hasGitLab = !!(gitlabEnv.token && gitlabEnv.projectId && gitlabEnv.mergeRequestIid);
+  if (hasGitLab) {
+    ui.progress("Posting GitLab MR note");
+    try {
+      await postMRComment(gitlabEnv, diff);
+      ui.progressDone("MR note posted");
+    } catch (err) {
+      ui.warn(`GitLab integration failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  if (!githubEnv.token && !hasGitLab) {
+    ui.info("CI platform:", "not detected (running locally)");
+    ui.info("Snapshot saved to:", outputPath);
+  }
+  ui.gap();
+}
+
+// src/commands/coverage.ts
+import { resolve } from "path";
+import {
+  loadCoverageData,
+  mapCoverageToComponents,
+  findUncoveredComponents,
+  findLowCoverageComponents,
+  summarizeCoverage
+} from "@foxlight/core";
+async function runCoverage(options) {
+  const projectRoot = resolve(options.root || ".");
+  const coverageData = await loadCoverageData(projectRoot, options.coveragePath);
+  if (Object.keys(coverageData).length === 0) {
+    console.log("\u274C No coverage data found.");
+    console.log("Make sure you have generated coverage with a tool like:");
+    console.log("  npm test -- --coverage (Jest/Vitest)");
+    console.log("  npx nyc npm test");
+    process.exit(1);
+  }
+  const componentFilePaths = new Set(Object.keys(coverageData));
+  const coverage = mapCoverageToComponents(coverageData, componentFilePaths);
+  if (options.json) {
+    const output = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      overall: coverage.overallPercentage,
+      components: Array.from(coverage.components.values()).map((c) => ({
+        filePath: c.filePath,
+        coverage: c.percentage,
+        statements: {
+          covered: c.statementsCovered,
+          total: c.statementsTotal
+        },
+        functions: {
+          covered: c.functionsCovered,
+          total: c.functionsTotal
+        }
+      }))
+    };
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+  console.log("\n\u{1F4CA} Test Coverage Report\n");
+  console.log(summarizeCoverage(coverage));
+  const uncovered = findUncoveredComponents(coverage);
+  if (uncovered.length > 0) {
+    console.log(`
+\u274C Uncovered Components (${uncovered.length}):`);
+    for (const comp of uncovered.slice(0, 10)) {
+      console.log(`  - ${comp.filePath}`);
+    }
+    if (uncovered.length > 10) {
+      console.log(`  ... and ${uncovered.length - 10} more`);
+    }
+  }
+  const threshold = options.threshold || 50;
+  const lowCoverage = findLowCoverageComponents(coverage, threshold);
+  if (lowCoverage.length > 0) {
+    console.log(`
+\u26A0\uFE0F  Low Coverage (<${threshold}%) (${lowCoverage.length}):`);
+    for (const comp of lowCoverage.slice(0, 15)) {
+      console.log(`  ${comp.filePath}: ${comp.percentage}%`);
+    }
+    if (lowCoverage.length > 15) {
+      console.log(`  ... and ${lowCoverage.length - 15} more
+`);
+    }
+  }
+  if (coverage.overallPercentage < threshold) {
+    console.log(`
+\u274C Coverage ${coverage.overallPercentage}% is below threshold ${threshold}%`);
+    process.exit(1);
+  }
+  console.log("");
+}
+
+// src/commands/dead-code.ts
+import { resolve as resolve2 } from "path";
+import { detectDeadCode, formatDeadCodeReport } from "@foxlight/core";
+import { analyzeProject as analyzeProject5 } from "@foxlight/analyzer";
+async function runDeadCodeDetection(options) {
+  const projectRoot = resolve2(options.root || ".");
+  console.log("\u{1F50D} Analyzing codebase for dead code...\n");
+  const analysis = await analyzeProject5(projectRoot);
+  const report = detectDeadCode(analysis.registry);
+  if (options.json) {
+    const output = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      summary: {
+        unusedComponents: report.unusedComponents.length,
+        orphanedComponents: report.orphanedComponents.length,
+        unusedExports: report.unusedExports.length,
+        potentialSavingsBytes: report.totalPotentialBytes
+      },
+      unusedComponents: report.unusedComponents.map((c) => ({
+        id: c.id,
+        name: c.name,
+        filePath: c.filePath,
+        reason: c.reason,
+        potentialSavings: c.potentialSavings
+      })),
+      orphanedComponents: report.orphanedComponents.map((c) => ({
+        id: c.id,
+        name: c.name,
+        filePath: c.filePath
+      })),
+      unusedExports: report.unusedExports.map((e) => ({
+        filePath: e.filePath,
+        exportName: e.exportName,
+        reason: e.reason
+      }))
+    };
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+  console.log(formatDeadCodeReport(report));
+  if (report.unusedComponents.length > 0) {
+    console.log("\n\u{1F4A1} Tip: These components can likely be safely removed.");
+    console.log("Run with --json for detailed analysis.");
+  }
+  const totalIssues = report.unusedComponents.length + report.orphanedComponents.length + report.unusedExports.length;
+  if (totalIssues === 0) {
+    console.log("\n\u2705 No dead code detected!");
+  } else {
+    console.log(`
+\u26A0\uFE0F  Found ${totalIssues} potential issues to address.
+`);
+  }
+}
+
+// src/commands/api-check.ts
+import { resolve as resolve3 } from "path";
+import { existsSync as existsSync2, readFileSync } from "fs";
+import { writeFile as writeFile2 } from "fs/promises";
+import { join as join2 } from "path";
+import {
+  createAPISnapshot,
+  snapshotToJSON,
+  snapshotFromJSON,
+  compareSnapshots as compareSnapshots2,
+  formatAPIChangeSummary
+} from "@foxlight/core";
+import { analyzeProject as analyzeProject6 } from "@foxlight/analyzer";
+var DEFAULT_SNAPSHOT_PATH = ".foxlight/api-baseline.json";
+async function runAPICheck(options) {
+  const projectRoot = resolve3(options.root || ".");
+  const snapshotPath = options.baseline || join2(projectRoot, DEFAULT_SNAPSHOT_PATH);
+  console.log("\u{1F50D} Checking for API breaking changes...\n");
+  const analysis = await analyzeProject6(projectRoot);
+  const currentComponents = analysis.registry.getAllComponents();
+  const currentSnapshot = createAPISnapshot(currentComponents);
+  let baselineSnapshot;
+  if (existsSync2(snapshotPath)) {
+    try {
+      const baselineJson = readFileSync(snapshotPath, "utf-8");
+      baselineSnapshot = snapshotFromJSON(baselineJson);
+    } catch {
+      console.log(`\u26A0\uFE0F  Could not load baseline snapshot from ${snapshotPath}`);
+      baselineSnapshot = null;
+    }
+  }
+  if (!baselineSnapshot) {
+    if (options.save) {
+      console.log("\u{1F4F8} Creating initial API baseline...");
+      await writeFile2(snapshotPath, snapshotToJSON(currentSnapshot));
+      console.log(`\u2705 API baseline saved to ${snapshotPath}
+`);
+      return;
+    } else {
+      console.log("\u2139\uFE0F  No baseline found. Run with --save to create one.");
+      console.log(`Expected baseline at: ${snapshotPath}
+`);
+      return;
+    }
+  }
+  const summary = compareSnapshots2(baselineSnapshot, currentSnapshot);
+  if (options.json) {
+    const output = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      breakingChanges: summary.breaking.map((c) => ({
+        component: c.componentName,
+        type: c.changeType,
+        severity: c.severity,
+        description: c.description
+      })),
+      addedComponents: summary.addedComponents.map((c) => c.name),
+      removedComponents: summary.removedComponents.map((c) => c.name),
+      totalBreakingChanges: summary.breaking.length
+    };
+    console.log(JSON.stringify(output, null, 2));
+    if (summary.breaking.length > 0) {
+      process.exit(1);
+    }
+    return;
+  }
+  console.log(formatAPIChangeSummary(summary));
+  if (options.save) {
+    console.log("\n\u{1F4F8} Updating API baseline...");
+    await writeFile2(snapshotPath, snapshotToJSON(currentSnapshot));
+    console.log(`\u2705 API baseline updated
+`);
+  }
+  if (summary.breaking.length > 0) {
+    console.log(
+      `
+\u274C Found ${summary.breaking.length} breaking change(s). Please review before merging.
+`
+    );
+    process.exit(1);
+  } else {
+    console.log("\n\u2705 No breaking changes detected.\n");
+  }
+}
+
+// src/index.ts
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  const flags = /* @__PURE__ */ new Map();
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const nextArg = args[i + 1];
+      const value = nextArg && !nextArg.startsWith("--") ? nextArg : "true";
+      flags.set(key, value);
+      if (value !== "true") i++;
+    }
+  }
+  const rootDir = resolve4(flags.get("root") ?? flags.get("dir") ?? ".");
+  const json = flags.has("json");
+  ui.banner();
+  switch (command) {
+    case "init":
+      await runInit({ rootDir });
+      break;
+    case "analyze":
+    case "scan":
+      await runAnalyze({ rootDir, json });
+      break;
+    case "health":
+    case "dashboard":
+      await runHealth({
+        rootDir,
+        json,
+        component: flags.get("component") ?? flags.get("c")
+      });
+      break;
+    case "cost":
+      await runCost({
+        rootDir,
+        json,
+        provider: flags.get("provider") ?? flags.get("p"),
+        pageViews: flags.has("page-views") ? parseInt(flags.get("page-views"), 10) : void 0
+      });
+      break;
+    case "upgrade": {
+      const packageName = args[1];
+      if (!packageName || packageName.startsWith("--")) {
+        ui.error("Please specify a package name: foxlight upgrade <package>");
+        process.exitCode = 1;
+        break;
+      }
+      await runUpgrade({
+        rootDir,
+        json,
+        packageName,
+        targetVersion: flags.get("to") ?? flags.get("target")
+      });
+      break;
+    }
+    case "ci":
+      await runCI({
+        rootDir,
+        json,
+        basePath: flags.get("base"),
+        outputPath: flags.get("output")
+      });
+      break;
+    case "coverage":
+      await runCoverage({
+        root: rootDir,
+        json,
+        threshold: flags.has("threshold") ? parseInt(flags.get("threshold"), 10) : void 0,
+        coveragePath: flags.get("coverage")
+      });
+      break;
+    case "dead-code":
+      await runDeadCodeDetection({
+        root: rootDir,
+        json,
+        threshold: flags.has("threshold") ? parseInt(flags.get("threshold"), 10) : void 0
+      });
+      break;
+    case "api-check":
+      await runAPICheck({
+        root: rootDir,
+        json,
+        save: flags.has("save"),
+        baseline: flags.get("baseline")
+      });
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+    case void 0:
+      printHelp();
+      break;
+    case "version":
+    case "--version":
+    case "-v":
+      console.log("  foxlight v0.1.0");
+      break;
+    default:
+      ui.error(`Unknown command: ${command}`);
+      ui.gap();
+      printHelp();
+      process.exitCode = 1;
+  }
+}
+function printHelp() {
+  console.log("  Usage: foxlight <command> [options]");
+  console.log("");
+  console.log("  Commands:");
+  console.log("    init              Initialize Foxlight in your project");
+  console.log("    analyze           Scan project and discover components");
+  console.log("    health            Show component health dashboard");
+  console.log("    cost              Estimate hosting costs by provider");
+  console.log("    upgrade <pkg>     Analyze dependency upgrade impact");
+  console.log("    coverage          Show test coverage by component");
+  console.log("    dead-code         Find unused components and exports");
+  console.log("    api-check         Detect breaking changes in component APIs");
+  console.log("    ci                Run CI analysis and post results");
+  console.log("");
+  console.log("  Options:");
+  console.log("    --root <dir>      Project root directory (default: .)");
+  console.log("    --json            Output results as JSON");
+  console.log("    --component <name> Filter health to a specific component");
+  console.log("    --provider <name> Cost provider (vercel, netlify, aws, cloudflare)");
+  console.log("    --to <version>    Target version for upgrade command");
+  console.log("    --threshold <num> Coverage/dead-code threshold");
+  console.log("    --coverage <path> Path to coverage JSON file");
+  console.log("    --save            Save current state as baseline (api-check)");
+  console.log("    --help            Show this help message");
+  console.log("    --version         Show version number");
+  console.log("");
+}
+main().catch((error) => {
+  ui.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@foxlight/cli",
+  "version": "0.1.0",
+  "description": "Command-line interface for Foxlight — analyze components, check health, run upgrades.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "foxlight": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "dependencies": {
+    "@foxlight/core": "*",
+    "@foxlight/analyzer": "*",
+    "@foxlight/bundle": "*",
+    "@foxlight/ci": "*"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "author": "Jose Cruz",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/josegabrielcruz/foxlight.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/josegabrielcruz/foxlight/tree/master/packages/cli#readme",
+  "bugs": {
+    "url": "https://github.com/josegabrielcruz/foxlight/issues"
+  },
+  "keywords": [
+    "foxlight",
+    "cli",
+    "component-health",
+    "frontend-tools"
+  ]
+}