@fragments-sdk/cli 0.15.0 → 0.15.2

package/src/commands/create.ts

@@ -0,0 +1,590 @@
+/**
+ * fragments create - Scaffold a new project with Fragments UI and a custom theme
+ *
+ * Mirrors the shadcn model: configure on the web (usefragments.com/create),
+ * then `npx @fragments-sdk/cli create` bootstraps a project with that config.
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, unlinkSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import pc from 'picocolors';
+import { BRAND } from '../core/index.js';
+import { decompressTheme } from '../theme/serializer.js';
+import { generateCssTokens, generateScssTokens } from '../theme/generator.js';
+import type { ThemeConfig } from '../theme/types.js';
+
+// ============================================
+// Font Helpers
+// ============================================
+
+/**
+ * Extract the primary font family name from a CSS font-stack string.
+ * e.g. '"Space Grotesk", sans-serif' → 'Space Grotesk'
+ */
+function extractFontFamily(cssFontStack: string): string | null {
+  const match = cssFontStack.match(/^["']?([^"',]+)["']?/);
+  if (!match) return null;
+  const name = match[1].trim();
+  const generics = ["sans-serif", "serif", "monospace", "cursive", "fantasy", "system-ui"];
+  if (generics.includes(name.toLowerCase())) return null;
+  if (name.toLowerCase() === "inter") return null; // Inter is the default, no need to load
+  return name;
+}
+
+function googleFontsUrl(familyName: string): string {
+  return `https://fonts.googleapis.com/css2?family=${encodeURIComponent(familyName)}:wght@400;500;600;700&display=swap`;
+}
+
+// ============================================
+// Types
+// ============================================
+
+export interface CreateOptions {
+  name?: string;
+  template?: 'nextjs' | 'vite';
+  packageManager?: 'npm' | 'pnpm' | 'yarn' | 'bun';
+  theme?: string;
+  preset?: string;
+  brand?: string;
+  scss?: boolean;
+  mcp?: boolean;
+  yes?: boolean;
+  noGit?: boolean;
+}
+
+export interface CreateResult {
+  success: boolean;
+  projectDir?: string;
+  error?: string;
+}
+
+// ============================================
+// Package Manager Detection
+// ============================================
+
+function detectPackageManager(): 'npm' | 'pnpm' | 'yarn' | 'bun' {
+  const agent = process.env.npm_config_user_agent || '';
+  if (agent.startsWith('pnpm')) return 'pnpm';
+  if (agent.startsWith('yarn')) return 'yarn';
+  if (agent.startsWith('bun')) return 'bun';
+  return 'npm';
+}
+
+function getInstallCommand(pm: string): string {
+  return pm === 'yarn' ? 'yarn add' : `${pm} add`;
+}
+
+function getDevInstallCommand(pm: string): string {
+  return pm === 'yarn' ? 'yarn add -D' : `${pm} add -D`;
+}
+
+function getRunCommand(pm: string): string {
+  return pm === 'npm' ? 'npm run' : pm;
+}
+
+// ============================================
+// Validation
+// ============================================
+
+function isValidProjectName(name: string): boolean {
+  return /^[a-z0-9][a-z0-9._-]*$/.test(name);
+}
+
+// ============================================
+// Theme Resolution
+// ============================================
+
+const PRESET_API_URL = 'https://canny-otter-874.convex.site/api/theme-presets';
+
+async function fetchPreset(presetId: string): Promise<ThemeConfig | null> {
+  try {
+    const res = await fetch(`${PRESET_API_URL}?id=${encodeURIComponent(presetId)}`);
+    if (!res.ok) return null;
+    const theme = await res.json();
+    if (!theme || !theme.name) return null;
+    return theme as ThemeConfig;
+  } catch {
+    return null;
+  }
+}
+
+async function resolveTheme(options: CreateOptions): Promise<ThemeConfig | null> {
+  if (options.preset) {
+    console.log(pc.dim(`  Fetching theme preset ${options.preset}...`));
+    const theme = await fetchPreset(options.preset);
+    if (!theme) {
+      console.error(pc.red(`Error: Could not fetch preset "${options.preset}". It may have expired or the ID is invalid.`));
+      return null;
+    }
+    return theme;
+  }
+
+  if (options.theme) {
+    const decoded = decompressTheme(options.theme);
+    if (!decoded) {
+      console.error(pc.red('Error: Could not decode theme string. Make sure you copied it from usefragments.com/create'));
+      return null;
+    }
+    return decoded;
+  }
+
+  if (options.brand) {
+    return {
+      name: 'custom',
+      colors: {
+        accent: options.brand,
+      },
+    };
+  }
+
+  return {
+    name: 'default',
+    colors: {
+      accent: '#6366f1',
+    },
+  };
+}
+
+// ============================================
+// Templates
+// ============================================
+
+export function generateNextjsLayout(themePath: string, theme?: ThemeConfig): string {
+  const fontName = theme?.typography?.fontSans ? extractFontFamily(theme.typography.fontSans) : null;
+  const fontUrl = fontName ? googleFontsUrl(fontName) : null;
+
+  const htmlOpen = fontUrl
+    ? `    <html lang="en" suppressHydrationWarning>
+      <head>
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="" />
+        <link href="${fontUrl}" rel="stylesheet" />
+      </head>
+      <body>`
+    : `    <html lang="en" suppressHydrationWarning>
+      <body>`;
+
+  return `import type { Metadata } from 'next';
+import '@fragments-sdk/ui/styles';
+import '${themePath}';
+import { Providers } from './providers';
+
+export const metadata: Metadata = {
+  title: 'My App',
+  description: 'Built with Fragments UI',
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+${htmlOpen}
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+`;
+}
+
+export function generateNextjsProviders(): string {
+  return `'use client';
+
+import type { ReactNode } from 'react';
+import { ThemeProvider, TooltipProvider, ToastProvider } from '@fragments-sdk/ui';
+
+export function Providers({ children }: { children: ReactNode }) {
+  return (
+    <ThemeProvider defaultMode="system">
+      <TooltipProvider>
+        <ToastProvider>{children}</ToastProvider>
+      </TooltipProvider>
+    </ThemeProvider>
+  );
+}
+`;
+}
+
+export function generateNextjsPage(): string {
+  return `'use client';
+
+import { Button, Card, Stack, Text, Input } from '@fragments-sdk/ui';
+
+export default function Home() {
+  return (
+    <main style={{ minHeight: '100vh', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
+      <Card style={{ maxWidth: 480, width: '100%' }}>
+        <Card.Header>
+          <Card.Title>Welcome to Fragments</Card.Title>
+          <Card.Description>Your app is ready. Start building something great.</Card.Description>
+        </Card.Header>
+        <Card.Body>
+          <Stack gap={3}>
+            <Input placeholder="Enter something..." />
+            <Stack direction="row" gap={2}>
+              <Button>Get Started</Button>
+              <Button variant="secondary">Learn More</Button>
+            </Stack>
+          </Stack>
+        </Card.Body>
+      </Card>
+    </main>
+  );
+}
+`;
+}
+
+function generateViteMain(themePath: string): string {
+  return `import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { ThemeProvider, TooltipProvider, ToastProvider } from '@fragments-sdk/ui';
+import '@fragments-sdk/ui/styles';
+import '${themePath}';
+import App from './App';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <ThemeProvider defaultMode="system">
+      <TooltipProvider>
+        <ToastProvider>
+          <App />
+        </ToastProvider>
+      </TooltipProvider>
+    </ThemeProvider>
+  </StrictMode>,
+);
+`;
+}
+
+function generateViteApp(): string {
+  return `import { Button, Card, Stack, Text, Input } from '@fragments-sdk/ui';
+
+function App() {
+  return (
+    <main style={{ minHeight: '100vh', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
+      <Card style={{ maxWidth: 480, width: '100%' }}>
+        <Card.Header>
+          <Card.Title>Welcome to Fragments</Card.Title>
+          <Card.Description>Your app is ready. Start building something great.</Card.Description>
+        </Card.Header>
+        <Card.Body>
+          <Stack gap={3}>
+            <Input placeholder="Enter something..." />
+            <Stack direction="row" gap={2}>
+              <Button>Get Started</Button>
+              <Button variant="secondary">Learn More</Button>
+            </Stack>
+          </Stack>
+        </Card.Body>
+      </Card>
+    </main>
+  );
+}
+
+export default App;
+`;
+}
+
+function injectFontIntoViteHtml(projectDir: string, theme: ThemeConfig): void {
+  const fontName = theme.typography?.fontSans ? extractFontFamily(theme.typography.fontSans) : null;
+  if (!fontName) return;
+
+  const indexPath = join(projectDir, "index.html");
+  if (!existsSync(indexPath)) return;
+
+  let html = readFileSync(indexPath, "utf-8");
+  const fontLinks = [
+    '    <link rel="preconnect" href="https://fonts.googleapis.com" />',
+    '    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />',
+    `    <link href="${googleFontsUrl(fontName)}" rel="stylesheet" />`,
+  ].join("\n");
+  html = html.replace("</head>", `${fontLinks}\n  </head>`);
+  writeFileSync(indexPath, html, "utf-8");
+}
+
+// ============================================
+// Scaffolding
+// ============================================
+
+async function promptIfMissing(options: CreateOptions): Promise<CreateOptions> {
+  const resolved = { ...options };
+
+  if (!resolved.name) {
+    if (resolved.yes) {
+      resolved.name = 'my-app';
+    } else {
+      try {
+        const { input } = await import('@inquirer/prompts');
+        resolved.name = await input({
+          message: 'Project name:',
+          default: 'my-app',
+          validate: (val) => isValidProjectName(val) || 'Use lowercase letters, numbers, hyphens, dots, underscores',
+        });
+      } catch {
+        resolved.name = 'my-app';
+      }
+    }
+  }
+
+  if (!resolved.template && !resolved.yes) {
+    try {
+      const { select } = await import('@inquirer/prompts');
+      resolved.template = await select({
+        message: 'Framework:',
+        choices: [
+          { name: 'Next.js (App Router)', value: 'nextjs' as const },
+          { name: 'Vite + React', value: 'vite' as const },
+        ],
+        default: 'nextjs',
+      });
+    } catch {
+      resolved.template = 'nextjs';
+    }
+  }
+
+  resolved.template = resolved.template || 'nextjs';
+  resolved.packageManager = resolved.packageManager || detectPackageManager();
+
+  return resolved;
+}
+
+function scaffoldFramework(name: string, template: string, pm: string): void {
+  console.log(pc.cyan(`\nScaffolding ${template === 'nextjs' ? 'Next.js' : 'Vite + React'} project...\n`));
+
+  if (template === 'nextjs') {
+    const cmd = `npx create-next-app@latest ${name} --ts --app --src-dir --no-tailwind --no-eslint --import-alias "@/*" --yes`;
+    execSync(cmd, { stdio: 'inherit' });
+  } else {
+    // Vite
+    if (pm === 'bun') {
+      execSync(`bun create vite ${name} --template react-ts`, { stdio: 'inherit' });
+    } else {
+      execSync(`npm create vite@latest ${name} -- --template react-ts`, { stdio: 'inherit' });
+    }
+  }
+}
+
+function installDeps(projectDir: string, pm: string, scss: boolean): void {
+  console.log(pc.cyan('\nInstalling Fragments UI...\n'));
+
+  const install = getInstallCommand(pm);
+  execSync(`${install} @fragments-sdk/ui`, { cwd: projectDir, stdio: 'inherit' });
+
+  if (scss) {
+    const devInstall = getDevInstallCommand(pm);
+    execSync(`${devInstall} sass`, { cwd: projectDir, stdio: 'inherit' });
+  }
+}
+
+function writeThemeFile(projectDir: string, theme: ThemeConfig, scss: boolean, template: string): string {
+  const stylesDir = join(projectDir, 'src', 'styles');
+  mkdirSync(stylesDir, { recursive: true });
+
+  const ext = scss ? 'scss' : 'css';
+  const content = scss ? generateScssTokens(theme) : generateCssTokens(theme);
+  const filePath = join(stylesDir, `theme.${ext}`);
+  writeFileSync(filePath, content, 'utf-8');
+
+  // Next.js layout is at src/app/layout.tsx → relative path is ../styles/theme.ext
+  // Vite main is at src/main.tsx → relative path is ./styles/theme.ext
+  if (template === 'nextjs') {
+    return `../styles/theme.${ext}`;
+  }
+  return `./styles/theme.${ext}`;
+}
+
+export function addNextTranspilePackages(projectDir: string): void {
+  const configCandidates = ['next.config.ts', 'next.config.mjs', 'next.config.js'];
+
+  for (const configFile of configCandidates) {
+    const fullPath = join(projectDir, configFile);
+    if (!existsSync(fullPath)) continue;
+
+    const content = readFileSync(fullPath, 'utf-8');
+
+    if (content.includes('transpilePackages') && content.includes('@fragments-sdk/ui')) {
+      return;
+    }
+
+    if (content.includes('transpilePackages')) {
+      return;
+    }
+
+    const patterns = [
+      {
+        search: /const\s+\w+\s*(?::\s*\w+)?\s*=\s*\{/,
+        replacement: (match: string) => `${match}\n  transpilePackages: ['@fragments-sdk/ui'],`,
+      },
+      {
+        search: /module\.exports\s*=\s*\{/,
+        replacement: (match: string) => `${match}\n  transpilePackages: ['@fragments-sdk/ui'],`,
+      },
+      {
+        search: /export\s+default\s*\{/,
+        replacement: (match: string) => `${match}\n  transpilePackages: ['@fragments-sdk/ui'],`,
+      },
+    ];
+
+    for (const pattern of patterns) {
+      if (!pattern.search.test(content)) continue;
+
+      writeFileSync(
+        fullPath,
+        content.replace(pattern.search, pattern.replacement),
+        'utf-8',
+      );
+      return;
+    }
+
+    return;
+  }
+}
+
+function rewriteAppFiles(projectDir: string, template: string, themePath: string, theme: ThemeConfig): void {
+  if (template === 'nextjs') {
+    // Rewrite layout.tsx
+    const layoutPath = join(projectDir, 'src', 'app', 'layout.tsx');
+    writeFileSync(layoutPath, generateNextjsLayout(themePath, theme), 'utf-8');
+
+    const providersPath = join(projectDir, 'src', 'app', 'providers.tsx');
+    writeFileSync(providersPath, generateNextjsProviders(), 'utf-8');
+
+    // Rewrite page.tsx
+    const pagePath = join(projectDir, 'src', 'app', 'page.tsx');
+    writeFileSync(pagePath, generateNextjsPage(), 'utf-8');
+
+    // Remove default page.module.css if it exists
+    const moduleCssPath = join(projectDir, 'src', 'app', 'page.module.css');
+    try {
+      unlinkSync(moduleCssPath);
+    } catch { /* doesn't exist, that's fine */ }
+
+    // Remove globals.css if it exists (we use our own theme)
+    const globalsCssPath = join(projectDir, 'src', 'app', 'globals.css');
+    try {
+      unlinkSync(globalsCssPath);
+    } catch { /* doesn't exist */ }
+
+    addNextTranspilePackages(projectDir);
+  } else {
+    // Vite: rewrite main.tsx and App.tsx
+    const mainPath = join(projectDir, 'src', 'main.tsx');
+    writeFileSync(mainPath, generateViteMain(themePath), 'utf-8');
+
+    const appPath = join(projectDir, 'src', 'App.tsx');
+    writeFileSync(appPath, generateViteApp(), 'utf-8');
+
+    // Clean up default Vite files
+    for (const file of ['src/App.css', 'src/index.css']) {
+      try {
+        unlinkSync(join(projectDir, file));
+      } catch { /* doesn't exist */ }
+    }
+
+    injectFontIntoViteHtml(projectDir, theme);
+  }
+}
+
+function initGit(projectDir: string): void {
+  try {
+    // create-next-app already inits git, so check first
+    if (!existsSync(join(projectDir, '.git'))) {
+      execSync('git init', { cwd: projectDir, stdio: 'ignore' });
+      execSync('git add -A', { cwd: projectDir, stdio: 'ignore' });
+      execSync('git commit -m "Initial commit with Fragments UI"', { cwd: projectDir, stdio: 'ignore' });
+    }
+  } catch {
+    // Git not available — skip silently
+  }
+}
+
+function configureMcp(projectDir: string): void {
+  const mcpConfig = {
+    mcpServers: {
+      fragments: {
+        command: 'npx',
+        args: ['-y', '@fragments-sdk/cli', 'mcp'],
+      },
+    },
+  };
+
+  const mcpDir = join(projectDir, '.mcp');
+  mkdirSync(mcpDir, { recursive: true });
+  writeFileSync(join(mcpDir, 'config.json'), JSON.stringify(mcpConfig, null, 2), 'utf-8');
+}
+
+// ============================================
+// Main
+// ============================================
+
+export async function create(options: CreateOptions): Promise<CreateResult> {
+  console.log(pc.cyan(`\n${BRAND.name} Create\n`));
+
+  // 1. Gather inputs
+  const resolved = await promptIfMissing(options);
+  const name = resolved.name!;
+  const template = resolved.template!;
+  const pm = resolved.packageManager!;
+
+  // 2. Validate
+  if (!isValidProjectName(name)) {
+    return { success: false, error: `Invalid project name: ${name}. Use lowercase letters, numbers, hyphens, dots, underscores.` };
+  }
+
+  const projectDir = resolve(process.cwd(), name);
+  if (existsSync(projectDir)) {
+    return { success: false, error: `Directory "${name}" already exists.` };
+  }
+
+  // 3. Resolve theme
+  const theme = await resolveTheme(resolved);
+  if (!theme) {
+    return { success: false, error: 'Invalid theme configuration.' };
+  }
+
+  // 4. Scaffold framework
+  scaffoldFramework(name, template, pm);
+
+  if (!existsSync(projectDir)) {
+    return { success: false, error: 'Framework scaffolding failed — project directory was not created.' };
+  }
+
+  // 5. Install deps
+  installDeps(projectDir, pm, !!resolved.scss);
+
+  // 6. Write theme tokens
+  const themePath = writeThemeFile(projectDir, theme, !!resolved.scss, template);
+
+  // 7. Rewrite app files with providers + theme import
+  rewriteAppFiles(projectDir, template, themePath, theme);
+
+  // 8. MCP config
+  if (resolved.mcp) {
+    configureMcp(projectDir);
+    console.log(pc.dim('  Configured MCP server for AI tooling'));
+  }
+
+  // 9. Git init
+  if (!resolved.noGit) {
+    initGit(projectDir);
+  }
+
+  // 10. Success message
+  const run = getRunCommand(pm);
+  console.log('');
+  console.log(pc.green('  Project created successfully!'));
+  console.log('');
+  console.log(`  ${pc.cyan('cd')} ${name}`);
+  console.log(`  ${pc.cyan(run)} dev`);
+  console.log('');
+
+  if (theme.name !== 'default') {
+    console.log(pc.dim(`  Theme "${theme.name}" applied with full token set.`));
+    console.log(pc.dim(`  Edit src/styles/theme.${resolved.scss ? 'scss' : 'css'} to customize.\n`));
+  }
+
+  return { success: true, projectDir };
+}

package/src/commands/doctor.ts

@@ -13,6 +13,7 @@ import { readFile, access } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import pc from 'picocolors';
 import { BRAND } from '../core/index.js';
+import { NEUTRAL_PALETTES } from '@fragments-sdk/viewer/docs-data';
 
 // ============================================
 // Types
@@ -43,10 +44,10 @@ export interface DoctorResult {
 }
 
 // ============================================
-// Valid seed values (match _seeds.scss)
+// Valid seed values — derived from canonical sources
 // ============================================
 
-const VALID_NEUTRALS = ['stone', 'ice', 'earth', 'sand', 'fire'];
+const VALID_NEUTRALS = NEUTRAL_PALETTES.map((p) => p.name);
 const VALID_DENSITIES = ['compact', 'default', 'relaxed'];
 const VALID_RADII = ['sharp', 'subtle', 'default', 'rounded', 'pill'];