@fragments-sdk/cli 0.9.0 → 0.10.0

package/src/commands/setup.ts

@@ -0,0 +1,499 @@
+/**
+ * fragments setup - Configure @fragments-sdk/ui in a consumer project
+ *
+ * Auto-detects framework (Next.js, Vite, etc.) and scaffolds:
+ * - Styles import in entry file
+ * - ThemeProvider wrapper in layout/app
+ * - transpilePackages for Next.js
+ * - SCSS seeds file (optional)
+ */
+
+import { readFile, writeFile, access, mkdir } from 'node:fs/promises';
+import { join, resolve, dirname } from 'node:path';
+import pc from 'picocolors';
+import { BRAND } from '../core/index.js';
+
+// ============================================
+// Types
+// ============================================
+
+export interface SetupOptions {
+  /** Project root directory (defaults to cwd) */
+  root?: string;
+  /** Skip interactive prompts */
+  yes?: boolean;
+  /** Brand color hex (e.g., #6366f1) */
+  brand?: string;
+  /** Include SCSS seed file */
+  scss?: boolean;
+  /** Configure MCP server for AI tooling */
+  mcp?: boolean;
+}
+
+export interface SetupResult {
+  success: boolean;
+  actions: string[];
+  errors: string[];
+}
+
+type Framework = 'nextjs-app' | 'nextjs-pages' | 'vite' | 'unknown';
+
+// ============================================
+// Detection
+// ============================================
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function detectFramework(root: string): Promise<Framework> {
+  // Next.js App Router
+  if (
+    await fileExists(join(root, 'app/layout.tsx')) ||
+    await fileExists(join(root, 'src/app/layout.tsx'))
+  ) {
+    return 'nextjs-app';
+  }
+
+  // Next.js Pages Router
+  if (
+    await fileExists(join(root, 'pages/_app.tsx')) ||
+    await fileExists(join(root, 'pages/_app.ts'))
+  ) {
+    return 'nextjs-pages';
+  }
+
+  // Next.js (config exists but no router detected yet)
+  if (
+    await fileExists(join(root, 'next.config.ts')) ||
+    await fileExists(join(root, 'next.config.js')) ||
+    await fileExists(join(root, 'next.config.mjs'))
+  ) {
+    return 'nextjs-app';
+  }
+
+  // Vite
+  if (
+    await fileExists(join(root, 'vite.config.ts')) ||
+    await fileExists(join(root, 'vite.config.js'))
+  ) {
+    return 'vite';
+  }
+
+  return 'unknown';
+}
+
+async function findEntryFile(root: string, framework: Framework): Promise<string | null> {
+  const candidates: string[] = [];
+
+  switch (framework) {
+    case 'nextjs-app':
+      candidates.push(
+        'src/app/layout.tsx', 'app/layout.tsx',
+        'src/app/layout.ts', 'app/layout.ts'
+      );
+      break;
+    case 'nextjs-pages':
+      candidates.push('pages/_app.tsx', 'pages/_app.ts');
+      break;
+    case 'vite':
+      candidates.push(
+        'src/main.tsx', 'src/main.ts',
+        'src/index.tsx', 'src/index.ts'
+      );
+      break;
+    default:
+      candidates.push(
+        'src/main.tsx', 'src/main.ts',
+        'src/index.tsx', 'src/index.ts',
+        'src/App.tsx', 'src/App.ts'
+      );
+  }
+
+  for (const candidate of candidates) {
+    if (await fileExists(join(root, candidate))) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+async function findNextConfig(root: string): Promise<string | null> {
+  const candidates = ['next.config.ts', 'next.config.mjs', 'next.config.js'];
+  for (const candidate of candidates) {
+    if (await fileExists(join(root, candidate))) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+// ============================================
+// Actions
+// ============================================
+
+async function addStylesImport(root: string, entryFile: string): Promise<{ modified: boolean; message: string }> {
+  const fullPath = join(root, entryFile);
+  const content = await readFile(fullPath, 'utf-8');
+
+  if (content.includes('@fragments-sdk/ui/styles')) {
+    return { modified: false, message: `Styles already imported in ${entryFile}` };
+  }
+
+  // Add import at the top of the file, after any 'use client' directive
+  const stylesImport = "import '@fragments-sdk/ui/styles';";
+  let newContent: string;
+
+  if (content.startsWith("'use client'") || content.startsWith('"use client"')) {
+    const directiveEnd = content.indexOf('\n') + 1;
+    newContent = content.slice(0, directiveEnd) + stylesImport + '\n' + content.slice(directiveEnd);
+  } else {
+    newContent = stylesImport + '\n' + content;
+  }
+
+  await writeFile(fullPath, newContent, 'utf-8');
+  return { modified: true, message: `Added styles import to ${entryFile}` };
+}
+
+async function addThemeProvider(root: string, entryFile: string, framework: Framework): Promise<{ modified: boolean; message: string }> {
+  const fullPath = join(root, entryFile);
+  const content = await readFile(fullPath, 'utf-8');
+
+  if (content.includes('ThemeProvider')) {
+    return { modified: false, message: `ThemeProvider already present in ${entryFile}` };
+  }
+
+  // For Next.js App Router, add import and wrap children
+  if (framework === 'nextjs-app') {
+    // Add import
+    const providerImport = "import { ThemeProvider, TooltipProvider, ToastProvider } from '@fragments-sdk/ui';";
+
+    let newContent = content;
+
+    // Find the last import line to add our import after it
+    const importLines = content.split('\n');
+    let lastImportIdx = -1;
+    for (let i = 0; i < importLines.length; i++) {
+      if (importLines[i].startsWith('import ') || importLines[i].startsWith("import '") || importLines[i].startsWith('import "')) {
+        lastImportIdx = i;
+      }
+    }
+
+    if (lastImportIdx >= 0) {
+      importLines.splice(lastImportIdx + 1, 0, providerImport);
+      newContent = importLines.join('\n');
+    } else {
+      newContent = providerImport + '\n' + content;
+    }
+
+    // Add suppressHydrationWarning hint and provider wrapping in a comment
+    // We can't safely auto-wrap JSX, so we add a guide comment instead
+    if (!content.includes('suppressHydrationWarning')) {
+      await writeFile(fullPath, newContent, 'utf-8');
+      return {
+        modified: true,
+        message: `Added provider imports to ${entryFile}. Wrap your {children} with:\n` +
+          `    <ThemeProvider defaultMode="system"><TooltipProvider><ToastProvider>{children}</ToastProvider></TooltipProvider></ThemeProvider>\n` +
+          `    Add suppressHydrationWarning to your <html> tag`,
+      };
+    }
+
+    await writeFile(fullPath, newContent, 'utf-8');
+    return { modified: true, message: `Added provider imports to ${entryFile}. Wrap {children} with ThemeProvider.` };
+  }
+
+  return { modified: false, message: 'Manual ThemeProvider setup needed — see https://usefragments.com/getting-started#provider-setup' };
+}
+
+async function addTranspilePackages(root: string): Promise<{ modified: boolean; message: string }> {
+  const configFile = await findNextConfig(root);
+  if (!configFile) {
+    return { modified: false, message: 'No next.config found' };
+  }
+
+  const fullPath = join(root, configFile);
+  const content = await readFile(fullPath, 'utf-8');
+
+  if (content.includes('transpilePackages') && content.includes('@fragments-sdk/ui')) {
+    return { modified: false, message: `transpilePackages already configured in ${configFile}` };
+  }
+
+  if (content.includes('transpilePackages')) {
+    // transpilePackages exists but without @fragments-sdk/ui — need manual addition
+    return {
+      modified: false,
+      message: `transpilePackages found in ${configFile} but missing '@fragments-sdk/ui'. Please add it manually.`,
+    };
+  }
+
+  // Add transpilePackages to the config
+  // Try to find the config object and add the property
+  const patterns = [
+    // const nextConfig = { ... }
+    { search: /const\s+\w+\s*=\s*\{/, replacement: (match: string) => `${match}\n  transpilePackages: ['@fragments-sdk/ui'],` },
+    // module.exports = { ... }
+    { search: /module\.exports\s*=\s*\{/, replacement: (match: string) => `${match}\n  transpilePackages: ['@fragments-sdk/ui'],` },
+    // export default { ... }
+    { search: /export\s+default\s*\{/, replacement: (match: string) => `${match}\n  transpilePackages: ['@fragments-sdk/ui'],` },
+  ];
+
+  for (const pattern of patterns) {
+    if (pattern.search.test(content)) {
+      const newContent = content.replace(pattern.search, pattern.replacement);
+      await writeFile(fullPath, newContent, 'utf-8');
+      return { modified: true, message: `Added transpilePackages to ${configFile}` };
+    }
+  }
+
+  return {
+    modified: false,
+    message: `Could not auto-modify ${configFile}. Add transpilePackages: ['@fragments-sdk/ui'] manually.`,
+  };
+}
+
+async function createScssSeeds(root: string, brand?: string): Promise<{ modified: boolean; message: string }> {
+  // Try common SCSS locations
+  const scssLocations = [
+    'src/app/globals.scss',
+    'app/globals.scss',
+    'src/styles/globals.scss',
+    'src/globals.scss',
+    'styles/globals.scss',
+  ];
+
+  // Check if any exists already
+  for (const loc of scssLocations) {
+    const fullPath = join(root, loc);
+    if (await fileExists(fullPath)) {
+      const content = await readFile(fullPath, 'utf-8');
+      if (content.includes('@fragments-sdk/ui/styles')) {
+        return { modified: false, message: `SCSS seeds already configured in ${loc}` };
+      }
+
+      // Prepend @use to existing file
+      const seedContent = generateScssSeedImport(brand);
+      const newContent = seedContent + '\n' + content;
+      await writeFile(fullPath, newContent, 'utf-8');
+      return { modified: true, message: `Added SCSS seed import to ${loc}` };
+    }
+  }
+
+  // Create new globals.scss in the most common location
+  const targetDir = await fileExists(join(root, 'src/app'))
+    ? 'src/app'
+    : await fileExists(join(root, 'src'))
+      ? 'src/styles'
+      : 'styles';
+
+  const targetPath = join(targetDir, 'globals.scss');
+  const fullPath = join(root, targetPath);
+
+  await mkdir(dirname(fullPath), { recursive: true });
+  await writeFile(fullPath, generateScssSeedImport(brand), 'utf-8');
+  return { modified: true, message: `Created ${targetPath} with SCSS seed configuration` };
+}
+
+async function setupMcpConfig(root: string): Promise<{ modified: boolean; message: string }> {
+  // Check common MCP config locations
+  const mcpConfigPaths = [
+    '.cursor/mcp.json',
+    '.vscode/mcp.json',
+  ];
+
+  for (const configPath of mcpConfigPaths) {
+    const fullPath = join(root, configPath);
+    if (await fileExists(fullPath)) {
+      try {
+        const content = await readFile(fullPath, 'utf-8');
+        const config = JSON.parse(content);
+        const servers = config.mcpServers || {};
+
+        // Check if fragments is already configured
+        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'));
+        });
+
+        if (hasFragments) {
+          return { modified: false, message: `MCP server already configured in ${configPath}` };
+        }
+
+        // Add fragments MCP server
+        servers.fragments = {
+          command: 'npx',
+          args: ['@fragments-sdk/mcp'],
+        };
+        config.mcpServers = servers;
+
+        await writeFile(fullPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+        return { modified: true, message: `Added Fragments MCP server to ${configPath}` };
+      } catch {
+        return { modified: false, message: `Could not parse ${configPath}` };
+      }
+    }
+  }
+
+  // No existing MCP config — create one for Cursor (most common)
+  const cursorDir = join(root, '.cursor');
+  const cursorMcpPath = join(cursorDir, 'mcp.json');
+
+  await mkdir(cursorDir, { recursive: true });
+  const mcpConfig = {
+    mcpServers: {
+      fragments: {
+        command: 'npx',
+        args: ['@fragments-sdk/mcp'],
+      },
+    },
+  };
+
+  await writeFile(cursorMcpPath, JSON.stringify(mcpConfig, null, 2) + '\n', 'utf-8');
+  return { modified: true, message: 'Created .cursor/mcp.json with Fragments MCP server' };
+}
+
+function generateScssSeedImport(brand?: string): string {
+  const brandColor = brand || '#0066ff';
+  return `@use '@fragments-sdk/ui/styles' with (
+  $fui-brand: ${brandColor},
+  $fui-neutral: "stone",
+  $fui-density: "default",
+  $fui-radius-style: "rounded"
+);
+`;
+}
+
+// ============================================
+// Main Setup Function
+// ============================================
+
+export async function setup(options: SetupOptions = {}): Promise<SetupResult> {
+  const root = resolve(options.root ?? process.cwd());
+  const actions: string[] = [];
+  const errors: string[] = [];
+
+  console.log(pc.cyan(`\n${BRAND.name} Setup\n`));
+
+  // 1. Detect framework
+  const framework = await detectFramework(root);
+  const frameworkLabel =
+    framework === 'nextjs-app' ? 'Next.js (App Router)' :
+    framework === 'nextjs-pages' ? 'Next.js (Pages Router)' :
+    framework === 'vite' ? 'Vite' :
+    'Unknown';
+
+  console.log(`  ${pc.dim('Framework:')} ${frameworkLabel}`);
+
+  // 2. Find entry file
+  const entryFile = await findEntryFile(root, framework);
+  if (entryFile) {
+    console.log(`  ${pc.dim('Entry:')} ${entryFile}`);
+  } else {
+    console.log(`  ${pc.yellow('!')} Could not detect entry file`);
+  }
+  console.log();
+
+  // 3. Add styles import
+  if (entryFile) {
+    try {
+      const result = await addStylesImport(root, entryFile);
+      const icon = result.modified ? pc.green('+') : pc.dim('·');
+      console.log(`  ${icon} ${result.message}`);
+      if (result.modified) actions.push(result.message);
+    } catch (error) {
+      const msg = `Failed to add styles import: ${error instanceof Error ? error.message : error}`;
+      console.log(`  ${pc.red('✗')} ${msg}`);
+      errors.push(msg);
+    }
+  }
+
+  // 4. Add ThemeProvider imports
+  if (entryFile) {
+    try {
+      const result = await addThemeProvider(root, entryFile, framework);
+      const icon = result.modified ? pc.green('+') : pc.dim('·');
+      console.log(`  ${icon} ${result.message}`);
+      if (result.modified) actions.push(result.message);
+    } catch (error) {
+      const msg = `Failed to add ThemeProvider: ${error instanceof Error ? error.message : error}`;
+      console.log(`  ${pc.red('✗')} ${msg}`);
+      errors.push(msg);
+    }
+  }
+
+  // 5. Next.js: add transpilePackages
+  if (framework === 'nextjs-app' || framework === 'nextjs-pages') {
+    try {
+      const result = await addTranspilePackages(root);
+      const icon = result.modified ? pc.green('+') : pc.dim('·');
+      console.log(`  ${icon} ${result.message}`);
+      if (result.modified) actions.push(result.message);
+    } catch (error) {
+      const msg = `Failed to update next.config: ${error instanceof Error ? error.message : error}`;
+      console.log(`  ${pc.red('✗')} ${msg}`);
+      errors.push(msg);
+    }
+  }
+
+  // 6. Create SCSS seeds file (if --scss flag or brand color specified)
+  if (options.scss || options.brand) {
+    try {
+      const result = await createScssSeeds(root, options.brand);
+      const icon = result.modified ? pc.green('+') : pc.dim('·');
+      console.log(`  ${icon} ${result.message}`);
+      if (result.modified) actions.push(result.message);
+    } catch (error) {
+      const msg = `Failed to create SCSS seeds: ${error instanceof Error ? error.message : error}`;
+      console.log(`  ${pc.red('✗')} ${msg}`);
+      errors.push(msg);
+    }
+  }
+
+  // 7. Configure MCP server (if --mcp flag)
+  if (options.mcp) {
+    try {
+      const result = await setupMcpConfig(root);
+      const icon = result.modified ? pc.green('+') : pc.dim('·');
+      console.log(`  ${icon} ${result.message}`);
+      if (result.modified) actions.push(result.message);
+    } catch (error) {
+      const msg = `Failed to configure MCP: ${error instanceof Error ? error.message : error}`;
+      console.log(`  ${pc.red('✗')} ${msg}`);
+      errors.push(msg);
+    }
+  }
+
+  // Summary
+  console.log();
+  if (errors.length > 0) {
+    console.log(pc.red(`  ${errors.length} error(s) occurred during setup`));
+  } else if (actions.length > 0) {
+    console.log(pc.green(`  ✓ Setup complete — ${actions.length} file(s) modified`));
+  } else {
+    console.log(pc.green('  ✓ Already configured — no changes needed'));
+  }
+
+  // Next steps
+  console.log();
+  console.log(pc.dim('  Next steps:'));
+  if (!options.scss && !options.brand) {
+    console.log(pc.dim('    • Run with --scss to add build-time theme seeds'));
+  }
+  if (!options.mcp) {
+    console.log(pc.dim('    • Run with --mcp to configure AI tooling (MCP server)'));
+  }
+  console.log(pc.dim('    • Run `fragments doctor` to verify your setup'));
+  console.log(pc.dim('    • Visit https://usefragments.com/getting-started'));
+  console.log();
+
+  return {
+    success: errors.length === 0,
+    actions,
+    errors,
+  };
+}

package/src/core/auto-props.ts

@@ -1,7 +1,7 @@
 import { existsSync, statSync } from "node:fs";
 import { dirname, extname, join, resolve } from "node:path";
 import ts from "typescript";
-import type { PropDefinition } from "./types.js";
+import type { PropDefinition } from '@fragments-sdk/core';
 
 export interface AutoDetectedPropDefinition {
   type: PropDefinition["type"];

package/src/core/bundle-measurer.ts

@@ -15,8 +15,8 @@ import {
   resolvePerformanceConfig,
   classifyComplexity,
   type PerformanceConfig,
-  type PerformanceData,
-} from './performance-presets.js';
+  type PerfData as PerformanceData,
+} from '@fragments-sdk/core';
 
 // ---------------------------------------------------------------------------
 // Types

package/src/core/config.ts

@@ -1,9 +1,15 @@
 import { existsSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { createJiti } from 'jiti';
-import { BRAND } from './constants.js';
-import type { FragmentsConfig } from './types.js';
-import { fragmentsConfigSchema } from './schema.js';
+import { BRAND, fragmentsConfigSchema } from '@fragments-sdk/core';
+import type { FragmentsConfig, StorybookFilterConfig } from '@fragments-sdk/core';
+
+const STORYBOOK_FILTER_DEFAULTS: StorybookFilterConfig = {
+  excludeDeprecated: true,
+  excludeTests: true,
+  excludeSvgIcons: true,
+  excludeSubComponents: true,
+};
 
 const DEFAULT_CONFIG: FragmentsConfig = {
   include: [
@@ -13,6 +19,7 @@ const DEFAULT_CONFIG: FragmentsConfig = {
   exclude: ['**/node_modules/**'],
   components: ['src/**/index.tsx', 'src/**/*.tsx'],
   framework: 'react',
+  storybook: STORYBOOK_FILTER_DEFAULTS,
   snippets: {
     mode: 'warn',
     scope: 'snippet+render',
@@ -77,8 +84,13 @@ export async function loadConfig(configPath?: string): Promise<{
       throw new Error(`Invalid config in ${resolvedPath}:\n${errors}`);
     }
 
+    const merged: FragmentsConfig = { ...DEFAULT_CONFIG, ...result.data };
+
+    // Deep-merge storybook filter defaults so consumers only override what they need
+    merged.storybook = { ...STORYBOOK_FILTER_DEFAULTS, ...result.data?.storybook };
+
     return {
-      config: { ...DEFAULT_CONFIG, ...result.data },
+      config: merged,
       configDir: dirname(resolvedPath),
     };
   } catch (error) {

package/src/core/discovery.ts

@@ -2,8 +2,8 @@ import { resolve, dirname, basename } from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import fg from 'fast-glob';
-import type { FragmentsConfig } from './types.js';
-import { BRAND } from './constants.js';
+import { BRAND } from '@fragments-sdk/core';
+import type { FragmentsConfig } from '@fragments-sdk/core';
 
 export interface DiscoveredFile {
   /** Absolute path to the file */

package/src/core/generators/context.ts

@@ -15,7 +15,7 @@ import type {
   RegistryPropEntry,
   FragmentDoNotItem,
   FragmentContextOptions,
-} from "../fragment-types.js";
+} from '@fragments-sdk/core';
 
 /**
  * Result of context generation

package/src/core/generators/registry.ts

@@ -11,15 +11,15 @@
 import { readFileSync, existsSync } from "node:fs";
 import { relative, dirname, basename, join } from "node:path";
 import fg from "fast-glob";
+import { BRAND } from '@fragments-sdk/core';
 import type {
   Fragment,
   FragmentRegistry,
   FragmentIndex,
   RegistryComponentEntry,
-} from "../fragment-types.js";
+  RegistryOptions,
+} from '@fragments-sdk/core';
 import { extractPropsFromFile } from "./typescript-extractor.js";
-import { BRAND } from "../constants.js";
-import type { RegistryOptions } from "../types.js";
 
 /**
  * Options for registry generation

package/src/core/generators/typescript-extractor.ts

@@ -5,7 +5,7 @@
 
 import ts from "typescript";
 import { readFileSync } from "node:fs";
-import type { RegistryPropEntry } from "../fragment-types.js";
+import type { RegistryPropEntry } from '@fragments-sdk/core';
 
 /**
  * Result of extracting props from a component file
@@ -13,6 +13,8 @@ import type { RegistryPropEntry } from "../fragment-types.js";
 export interface ExtractedProps {
   /** Component name */
   componentName: string;
+  /** Whether the component uses export default */
+  isDefaultExport?: boolean;
   /** Props interface name (e.g., "ButtonProps") */
   propsInterfaceName?: string;
   /** Extracted props */
@@ -56,6 +58,7 @@ export function extractPropsFromSource(
   // Find all exports and props interfaces
   const propsInterfaces = new Map<string, ts.InterfaceDeclaration | ts.TypeAliasDeclaration>();
   const componentExports: string[] = [];
+  const defaultExports = new Set<string>();
   const importedModules: string[] = [];
 
   ts.forEachChild(sourceFile, (node) => {
@@ -88,8 +91,14 @@ export function extractPropsFromSource(
       const hasExport = node.modifiers?.some(
         (m) => m.kind === ts.SyntaxKind.ExportKeyword
       );
+      const hasDefault = node.modifiers?.some(
+        (m) => m.kind === ts.SyntaxKind.DefaultKeyword
+      );
       if (hasExport) {
         componentExports.push(node.name.text);
+        if (hasDefault) {
+          defaultExports.add(node.name.text);
+        }
       }
     }
 
@@ -130,6 +139,7 @@ export function extractPropsFromSource(
   }
 
   result.componentName = mainComponent;
+  result.isDefaultExport = defaultExports.has(mainComponent);
 
   // Find matching props interface
   const propsInterfaceName = `${mainComponent}Props`;

package/src/core/graph-extractor.ts

@@ -24,7 +24,7 @@ import type {
   GraphHealth,
 } from '@fragments-sdk/context/graph';
 import { EDGE_TYPE_WEIGHTS, computeHealthFromData } from '@fragments-sdk/context/graph';
-import type { CompiledFragment, CompiledBlock } from './types.js';
+import type { CompiledFragment, CompiledBlock } from '@fragments-sdk/core';
 
 // ---------------------------------------------------------------------------
 // Public API