@fragments-sdk/cli 0.8.1 → 0.9.0

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;
+}

package/src/commands/init-framework.ts

@@ -126,7 +126,7 @@ import { ThemeProvider } from '@fragments-sdk/ui';
 
 export function Providers({ children }: { children: React.ReactNode }) {
   return (
-    <ThemeProvider defaultTheme="system" attribute="data-theme">
+    <ThemeProvider defaultMode="system" attribute="data-theme">
       {children}
     </ThemeProvider>
   );

package/src/viewer/server.ts

@@ -253,6 +253,9 @@ export async function createDevServer(
   const sharedLibRoot = resolveSharedLib();
   const webmcpLibRoot = resolveWebMCPLib(nodeModulesPath);
   const contextLibRoot = resolveContextLib(nodeModulesPath);
+  // Detect whether resolved libs point to source (.ts) or dist (.js)
+  const isWebMCPSource = existsSync(join(webmcpLibRoot, "react/index.ts"));
+  const isContextSource = existsSync(join(contextLibRoot, "types/index.ts"));
   console.log(`📁 Using node_modules: ${nodeModulesPath}`);
 
   // Collect installed package roots so Vite can serve files from node_modules
@@ -322,12 +325,20 @@ export async function createDevServer(
         // Resolve @fragments-sdk/shared to monorepo source or vendored fallback
         "@fragments-sdk/shared": sharedLibRoot,
         // Resolve @fragments-sdk/webmcp subpaths to monorepo source or installed package
-        "@fragments-sdk/webmcp/react": join(webmcpLibRoot, "react/index.ts"),
-        "@fragments-sdk/webmcp/fragments": join(webmcpLibRoot, "fragments/index.ts"),
+        "@fragments-sdk/webmcp/react": isWebMCPSource
+          ? join(webmcpLibRoot, "react/index.ts")
+          : join(webmcpLibRoot, "dist/react/index.js"),
+        "@fragments-sdk/webmcp/fragments": isWebMCPSource
+          ? join(webmcpLibRoot, "fragments/index.ts")
+          : join(webmcpLibRoot, "dist/fragments/index.js"),
         "@fragments-sdk/webmcp": webmcpLibRoot,
         // Resolve @fragments-sdk/context subpaths to monorepo source or installed package
-        "@fragments-sdk/context/types": join(contextLibRoot, "types/index.ts"),
-        "@fragments-sdk/context/mcp-tools": join(contextLibRoot, "mcp-tools/index.ts"),
+        "@fragments-sdk/context/types": isContextSource
+          ? join(contextLibRoot, "types/index.ts")
+          : join(contextLibRoot, "dist/types/index.js"),
+        "@fragments-sdk/context/mcp-tools": isContextSource
+          ? join(contextLibRoot, "mcp-tools/index.ts")
+          : join(contextLibRoot, "dist/mcp-tools/index.js"),
         "@fragments-sdk/context": contextLibRoot,
         // Resolve @fragments-sdk/cli/core to the CLI's own core source
         "@fragments-sdk/cli/core": resolve(cliPackageRoot, "src/core/index.ts"),

package/src/viewer/vendor/shared/src/DocsHeaderBar.tsx

@@ -20,6 +20,8 @@ interface DocsHeaderBarProps {
   navAriaLabel?: string;
 }
 
+const EMPTY_SECTIONS: NavSection[] = [];
+
 const defaultLinkRenderer: DocsNavLinkRenderer = ({ href, label, onClick }) => (
   <a href={href} onClick={onClick}>
     {label}
@@ -30,10 +32,20 @@ function defaultIsActive(href: string, currentPath: string): boolean {
   return currentPath === href || currentPath.startsWith(`${href}/`);
 }
 
+/** Named component wrapper to avoid inline render functions in JSX */
+function NavLink({ renderer, href, label, onClick }: {
+  renderer: DocsNavLinkRenderer;
+  href: string;
+  label: string;
+  onClick?: () => void;
+}) {
+  return <>{renderer({ href, label, onClick })}</>;
+}
+
 export function DocsHeaderBar({
   brand,
   headerNav,
-  mobileSections = [],
+  mobileSections = EMPTY_SECTIONS,
   currentPath,
   searchItems,
   onSearchSelect,
@@ -63,7 +75,7 @@ export function DocsHeaderBar({
                         active={isActive(child.href, currentPath)}
                         asChild
                       >
-                        {renderLink({ href: child.href, label: child.label })}
+                        <NavLink renderer={renderLink} href={child.href} label={child.label} />
                       </NavigationMenu.Link>
                     ))}
                   </div>
@@ -76,7 +88,7 @@ export function DocsHeaderBar({
                   active={isActive(entry.href, currentPath)}
                   asChild
                 >
-                  {renderLink({ href: entry.href, label: entry.label })}
+                  <NavLink renderer={renderLink} href={entry.href} label={entry.label} />
                 </NavigationMenu.Link>
               </NavigationMenu.Item>
             )
@@ -94,12 +106,12 @@ export function DocsHeaderBar({
               isDropdown(entry) ? (
                 entry.items.map((child) => (
                   <NavigationMenu.Link key={child.href} href={child.href} asChild>
-                    {renderLink({ href: child.href, label: child.label })}
+                    <NavLink renderer={renderLink} href={child.href} label={child.label} />
                   </NavigationMenu.Link>
                 ))
               ) : (
                 <NavigationMenu.Link key={entry.href} href={entry.href} asChild>
-                  {renderLink({ href: entry.href, label: entry.label })}
+                  <NavLink renderer={renderLink} href={entry.href} label={entry.label} />
                 </NavigationMenu.Link>
               )
             )}
@@ -109,7 +121,7 @@ export function DocsHeaderBar({
             <NavigationMenu.MobileSection key={section.title} label={section.title}>
               {section.items.map((item) => (
                 <NavigationMenu.Link key={item.href} href={item.href} asChild>
-                  {renderLink({ href: item.href, label: item.label })}
+                  <NavLink renderer={renderLink} href={item.href} label={item.label} />
                 </NavigationMenu.Link>
               ))}
             </NavigationMenu.MobileSection>

package/src/viewer/vendor/shared/src/DocsSidebarNav.tsx

@@ -24,6 +24,16 @@ const defaultLinkRenderer: DocsNavLinkRenderer = ({ href, label, onClick }) => (
   </a>
 );
 
+/** Named component wrapper to avoid inline render functions in JSX */
+function SidebarLink({ renderer, href, label, onClick }: {
+  renderer: DocsNavLinkRenderer;
+  href: string;
+  label: string;
+  onClick?: () => void;
+}) {
+  return <>{renderer({ href, label, onClick })}</>;
+}
+
 export function DocsSidebarNav({
   sections,
   currentPath,
@@ -49,11 +59,12 @@ export function DocsSidebarNav({
                 active={isActive(item.href, currentPath)}
                 asChild
               >
-                {renderLink({
-                  href: item.href,
-                  label: item.label,
-                  onClick: onNavigate,
-                })}
+                <SidebarLink
+                  renderer={renderLink}
+                  href={item.href}
+                  label={item.label}
+                  onClick={onNavigate}
+                />
               </Sidebar.Item>
             ))}
           </Sidebar.Section>

package/src/viewer/vendor/shared/src/docs-data/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Docs data — single source of truth for content shared across
+ * READMEs, docs pages, and MCP tool descriptions.
+ *
+ * Follows the same pattern as `cli-commands/index.ts`.
+ */
+
+export {
+  NEUTRAL_PALETTES,
+  DENSITY_PRESETS,
+  RADIUS_STYLES,
+  SEED_DEFAULTS,
+  type PaletteDef,
+  type DensityDef,
+  type RadiusDef,
+} from './palettes.js';
+
+export {
+  SCSS_SETUP_MINIMAL,
+  SCSS_SETUP_FULL,
+  USE_THEME_EXAMPLE,
+  USE_THEME_RETURN_SHAPE,
+  PROVIDER_SETUP_EXAMPLE,
+  MIXIN_IMPORT,
+  STYLES_IMPORT_JS,
+  STYLES_IMPORT_SCSS,
+} from './setup-examples.js';
+
+export {
+  MCP_CONFIGS,
+  type McpConfigDef,
+} from './mcp-configs.js';