@fragments-sdk/cli 0.8.1 → 0.9.1

package/src/commands/doctor.ts

@@ -0,0 +1,498 @@
+/**
+ * fragments doctor - Diagnose design system configuration
+ *
+ * Checks a consumer project for common setup issues:
+ * - Missing styles import
+ * - ThemeProvider not found
+ * - Invalid SCSS seed values
+ * - Missing peer dependencies
+ * - MCP configuration
+ */
+
+import { readFile, access } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import pc from 'picocolors';
+import { BRAND } from '../core/index.js';
+
+// ============================================
+// Types
+// ============================================
+
+export interface DoctorOptions {
+  /** Project root directory (defaults to cwd) */
+  root?: string;
+  /** Output JSON instead of formatted text */
+  json?: boolean;
+  /** Auto-fix issues where possible */
+  fix?: boolean;
+}
+
+export interface DoctorCheck {
+  name: string;
+  status: 'pass' | 'warn' | 'fail';
+  message: string;
+  fix?: string;
+}
+
+export interface DoctorResult {
+  success: boolean;
+  checks: DoctorCheck[];
+  passed: number;
+  warned: number;
+  failed: number;
+}
+
+// ============================================
+// Valid seed values (match _seeds.scss)
+// ============================================
+
+const VALID_NEUTRALS = ['stone', 'ice', 'earth', 'sand', 'fire'];
+const VALID_DENSITIES = ['compact', 'default', 'relaxed'];
+const VALID_RADII = ['sharp', 'subtle', 'default', 'rounded', 'pill'];
+
+// ============================================
+// Individual Checks
+// ============================================
+
+async function checkPackageInstalled(root: string): Promise<DoctorCheck> {
+  try {
+    const pkgPath = join(root, 'package.json');
+    const content = await readFile(pkgPath, 'utf-8');
+    const pkg = JSON.parse(content);
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+    if (allDeps['@fragments-sdk/ui']) {
+      return {
+        name: 'Package installed',
+        status: 'pass',
+        message: `@fragments-sdk/ui ${allDeps['@fragments-sdk/ui']} found in dependencies`,
+      };
+    }
+
+    return {
+      name: 'Package installed',
+      status: 'fail',
+      message: '@fragments-sdk/ui not found in package.json',
+      fix: 'npm install @fragments-sdk/ui',
+    };
+  } catch {
+    return {
+      name: 'Package installed',
+      status: 'fail',
+      message: 'No package.json found',
+    };
+  }
+}
+
+async function checkStylesImport(root: string): Promise<DoctorCheck> {
+  const entryPatterns = [
+    'src/main.tsx', 'src/main.ts', 'src/index.tsx', 'src/index.ts',
+    'src/App.tsx', 'src/App.ts',
+    'app/layout.tsx', 'app/layout.ts',
+    'src/app/layout.tsx', 'src/app/layout.ts',
+    'app/root.tsx',
+    'pages/_app.tsx', 'pages/_app.ts',
+  ];
+
+  for (const pattern of entryPatterns) {
+    try {
+      const content = await readFile(join(root, pattern), 'utf-8');
+
+      // Check for correct import
+      if (content.includes("@fragments-sdk/ui/styles")) {
+        return {
+          name: 'Styles import',
+          status: 'pass',
+          message: `Found styles import in ${pattern}`,
+        };
+      }
+
+      // Check for deprecated ./globals import
+      if (content.includes("@fragments-sdk/ui/globals")) {
+        return {
+          name: 'Styles import',
+          status: 'warn',
+          message: `${pattern} uses deprecated '@fragments-sdk/ui/globals'. Use '@fragments-sdk/ui/styles' instead`,
+          fix: `Replace '@fragments-sdk/ui/globals' with '@fragments-sdk/ui/styles' in ${pattern}`,
+        };
+      }
+    } catch {
+      // File doesn't exist, continue
+    }
+  }
+
+  // Also check SCSS files for @use import
+  const scssPatterns = [
+    'src/styles/globals.scss', 'src/globals.scss',
+    'styles/globals.scss', 'app/globals.scss',
+    'src/app/globals.scss',
+    'app/styles/globals.scss',
+  ];
+
+  for (const pattern of scssPatterns) {
+    try {
+      const content = await readFile(join(root, pattern), 'utf-8');
+      if (content.includes("@fragments-sdk/ui/styles")) {
+        return {
+          name: 'Styles import',
+          status: 'pass',
+          message: `Found SCSS @use import in ${pattern}`,
+        };
+      }
+    } catch {
+      // File doesn't exist, continue
+    }
+  }
+
+  return {
+    name: 'Styles import',
+    status: 'fail',
+    message: 'No @fragments-sdk/ui/styles import found in entry files',
+    fix: "Add `import '@fragments-sdk/ui/styles'` to your app's entry file",
+  };
+}
+
+async function checkThemeProvider(root: string): Promise<DoctorCheck> {
+  const providerPatterns = [
+    'src/main.tsx', 'src/App.tsx', 'src/providers.tsx',
+    'app/layout.tsx', 'app/providers.tsx',
+    'src/app/layout.tsx', 'src/app/providers.tsx',
+    'app/root.tsx',
+    'pages/_app.tsx',
+  ];
+
+  for (const pattern of providerPatterns) {
+    try {
+      const content = await readFile(join(root, pattern), 'utf-8');
+
+      if (content.includes('ThemeProvider')) {
+        // Check for deprecated defaultTheme prop
+        if (content.includes('defaultTheme=') || content.includes('defaultTheme =')) {
+          return {
+            name: 'ThemeProvider',
+            status: 'warn',
+            message: `${pattern} uses deprecated 'defaultTheme' prop. Use 'defaultMode' instead`,
+            fix: `Replace 'defaultTheme' with 'defaultMode' in ${pattern}`,
+          };
+        }
+
+        return {
+          name: 'ThemeProvider',
+          status: 'pass',
+          message: `ThemeProvider found in ${pattern}`,
+        };
+      }
+    } catch {
+      // File doesn't exist, continue
+    }
+  }
+
+  return {
+    name: 'ThemeProvider',
+    status: 'warn',
+    message: 'ThemeProvider not found in common entry files (optional but recommended)',
+    fix: "Wrap your app with <ThemeProvider defaultMode=\"system\">",
+  };
+}
+
+async function checkScssSeeds(root: string): Promise<DoctorCheck[]> {
+  const checks: DoctorCheck[] = [];
+
+  const scssPatterns = [
+    'src/styles/globals.scss', 'src/globals.scss',
+    'styles/globals.scss', 'app/globals.scss',
+    'src/app/globals.scss',
+    'app/styles/globals.scss',
+  ];
+
+  for (const pattern of scssPatterns) {
+    try {
+      const content = await readFile(join(root, pattern), 'utf-8');
+      if (!content.includes("@fragments-sdk/ui/styles")) continue;
+
+      // Check for standalone variable syntax (wrong)
+      const standalonePattern = /^\$fui-\w+:\s*.+;$/m;
+      if (standalonePattern.test(content) && !content.includes('@use')) {
+        checks.push({
+          name: 'SCSS syntax',
+          status: 'fail',
+          message: `${pattern} uses standalone $fui- variables. Must use @use...with() syntax`,
+          fix: "@use '@fragments-sdk/ui/styles' with ($fui-brand: #0066ff);",
+        });
+      }
+
+      // Validate neutral value
+      const neutralMatch = content.match(/\$fui-neutral:\s*"([^"]+)"/);
+      if (neutralMatch && !VALID_NEUTRALS.includes(neutralMatch[1])) {
+        checks.push({
+          name: 'SCSS seed: neutral',
+          status: 'fail',
+          message: `Invalid $fui-neutral: "${neutralMatch[1]}" in ${pattern}`,
+          fix: `Valid neutrals: ${VALID_NEUTRALS.join(', ')}`,
+        });
+      }
+
+      // Validate density value
+      const densityMatch = content.match(/\$fui-density:\s*"([^"]+)"/);
+      if (densityMatch && !VALID_DENSITIES.includes(densityMatch[1])) {
+        checks.push({
+          name: 'SCSS seed: density',
+          status: 'fail',
+          message: `Invalid $fui-density: "${densityMatch[1]}" in ${pattern}`,
+          fix: `Valid densities: ${VALID_DENSITIES.join(', ')}`,
+        });
+      }
+
+      // Validate radius-style value
+      const radiusMatch = content.match(/\$fui-radius-style:\s*"([^"]+)"/);
+      if (radiusMatch && !VALID_RADII.includes(radiusMatch[1])) {
+        checks.push({
+          name: 'SCSS seed: radius-style',
+          status: 'fail',
+          message: `Invalid $fui-radius-style: "${radiusMatch[1]}" in ${pattern}`,
+          fix: `Valid radius styles: ${VALID_RADII.join(', ')}`,
+        });
+      }
+
+      // Validate brand is a valid hex color
+      const brandMatch = content.match(/\$fui-brand:\s*(#[0-9a-fA-F]+)/);
+      if (brandMatch) {
+        const hex = brandMatch[1];
+        if (!/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(hex)) {
+          checks.push({
+            name: 'SCSS seed: brand',
+            status: 'fail',
+            message: `Invalid $fui-brand color: "${hex}" in ${pattern}`,
+            fix: 'Must be a valid hex color (e.g., #0066ff)',
+          });
+        }
+      }
+
+      // If we found the file and parsed it, and no seed issues, add a pass
+      if (checks.length === 0) {
+        checks.push({
+          name: 'SCSS seeds',
+          status: 'pass',
+          message: `Seed values in ${pattern} are valid`,
+        });
+      }
+
+      return checks;
+    } catch {
+      // File doesn't exist, continue
+    }
+  }
+
+  // No SCSS file found — not an error, just informational
+  checks.push({
+    name: 'SCSS seeds',
+    status: 'pass',
+    message: 'No custom SCSS seeds configured (using defaults)',
+  });
+
+  return checks;
+}
+
+async function checkPeerDeps(root: string): Promise<DoctorCheck[]> {
+  const checks: DoctorCheck[] = [];
+
+  try {
+    const pkgPath = join(root, 'package.json');
+    const content = await readFile(pkgPath, 'utf-8');
+    const pkg = JSON.parse(content);
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+    // React is required
+    if (!allDeps['react']) {
+      checks.push({
+        name: 'Peer dep: react',
+        status: 'fail',
+        message: 'react not found in dependencies (required)',
+        fix: 'npm install react react-dom',
+      });
+    } else {
+      checks.push({
+        name: 'Peer dep: react',
+        status: 'pass',
+        message: `react ${allDeps['react']} installed`,
+      });
+    }
+
+    // sass is needed for custom theming
+    if (!allDeps['sass']) {
+      checks.push({
+        name: 'Peer dep: sass',
+        status: 'warn',
+        message: 'sass not installed (needed for custom SCSS theming)',
+        fix: 'npm install -D sass',
+      });
+    }
+
+    // Check optional peer deps that components might need
+    const optionalPeers: Array<{ pkg: string; components: string }> = [
+      { pkg: 'recharts', components: 'Chart' },
+      { pkg: 'shiki', components: 'CodeBlock' },
+      { pkg: 'react-day-picker', components: 'DatePicker' },
+      { pkg: '@tanstack/react-table', components: 'DataTable' },
+    ];
+
+    for (const peer of optionalPeers) {
+      if (allDeps[peer.pkg]) {
+        checks.push({
+          name: `Optional dep: ${peer.pkg}`,
+          status: 'pass',
+          message: `${peer.pkg} installed (enables ${peer.components})`,
+        });
+      }
+    }
+  } catch {
+    checks.push({
+      name: 'Peer dependencies',
+      status: 'fail',
+      message: 'Could not read package.json',
+    });
+  }
+
+  return checks;
+}
+
+async function checkMcpConfig(root: string): Promise<DoctorCheck> {
+  const mcpConfigPaths = [
+    '.mcp.json',
+    '.cursor/mcp.json',
+    '.vscode/mcp.json',
+  ];
+
+  for (const configPath of mcpConfigPaths) {
+    try {
+      const fullPath = join(root, configPath);
+      const content = await readFile(fullPath, 'utf-8');
+      const config = JSON.parse(content);
+
+      // Check if fragments MCP server is configured
+      const servers = config.mcpServers || config.servers || {};
+      const hasFragments = Object.values(servers).some((server: unknown) => {
+        const s = server as { command?: string; args?: string[] };
+        return (
+          s.args?.some((arg: string) => arg.includes('@fragments-sdk/mcp')) ||
+          s.command?.includes('fragments')
+        );
+      });
+
+      if (hasFragments) {
+        return {
+          name: 'MCP configuration',
+          status: 'pass',
+          message: `Fragments MCP server configured in ${configPath}`,
+        };
+      }
+    } catch {
+      // File doesn't exist or is invalid, continue
+    }
+  }
+
+  return {
+    name: 'MCP configuration',
+    status: 'warn',
+    message: 'No Fragments MCP server configuration found (optional)',
+    fix: 'Run `fragments init` or add @fragments-sdk/mcp to your MCP config',
+  };
+}
+
+async function checkTypeScript(root: string): Promise<DoctorCheck> {
+  try {
+    const tsconfigPath = join(root, 'tsconfig.json');
+    await access(tsconfigPath);
+    return {
+      name: 'TypeScript',
+      status: 'pass',
+      message: 'tsconfig.json found',
+    };
+  } catch {
+    return {
+      name: 'TypeScript',
+      status: 'warn',
+      message: 'No tsconfig.json found (TypeScript recommended but not required)',
+    };
+  }
+}
+
+// ============================================
+// Main Doctor Function
+// ============================================
+
+/**
+ * Run diagnostic checks on a consumer project
+ */
+export async function doctor(
+  options: DoctorOptions = {}
+): Promise<DoctorResult> {
+  const root = resolve(options.root ?? process.cwd());
+  const checks: DoctorCheck[] = [];
+
+  if (!options.json) {
+    console.log(pc.cyan(`\n${BRAND.name} Doctor\n`));
+    console.log(pc.dim(`Checking project at ${root}\n`));
+  }
+
+  // Run all checks
+  checks.push(await checkPackageInstalled(root));
+  checks.push(await checkStylesImport(root));
+  checks.push(await checkThemeProvider(root));
+  checks.push(...await checkScssSeeds(root));
+  checks.push(...await checkPeerDeps(root));
+  checks.push(await checkMcpConfig(root));
+  checks.push(await checkTypeScript(root));
+
+  const passed = checks.filter(c => c.status === 'pass').length;
+  const warned = checks.filter(c => c.status === 'warn').length;
+  const failed = checks.filter(c => c.status === 'fail').length;
+
+  const result: DoctorResult = {
+    success: failed === 0,
+    checks,
+    passed,
+    warned,
+    failed,
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    // Print results
+    for (const check of checks) {
+      const icon =
+        check.status === 'pass' ? pc.green('✓') :
+        check.status === 'warn' ? pc.yellow('!') :
+        pc.red('✗');
+
+      const msg =
+        check.status === 'pass' ? check.message :
+        check.status === 'warn' ? pc.yellow(check.message) :
+        pc.red(check.message);
+
+      console.log(`  ${icon} ${pc.bold(check.name)}: ${msg}`);
+
+      if (check.fix && check.status !== 'pass') {
+        console.log(pc.dim(`    → ${check.fix}`));
+      }
+    }
+
+    // Summary
+    console.log();
+    if (failed === 0 && warned === 0) {
+      console.log(pc.green(`✓ All ${passed} checks passed — your setup looks great!`));
+    } else if (failed === 0) {
+      console.log(pc.green(`✓ ${passed} passed`) + pc.yellow(`, ${warned} warning(s)`));
+    } else {
+      console.log(
+        pc.red(`✗ ${failed} failed`) +
+        (warned > 0 ? pc.yellow(`, ${warned} warning(s)`) : '') +
+        pc.dim(`, ${passed} passed`)
+      );
+    }
+    console.log();
+  }
+
+  return result;
+}