@fragments-sdk/cli 0.14.3 → 0.15.1

package/src/commands/create.ts

@@ -0,0 +1,536 @@
+/**
+ * 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';
+
+// ============================================
+// 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): string {
+  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 (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <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;
+`;
+}
+
+// ============================================
+// 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): void {
+  if (template === 'nextjs') {
+    // Rewrite layout.tsx
+    const layoutPath = join(projectDir, 'src', 'app', 'layout.tsx');
+    writeFileSync(layoutPath, generateNextjsLayout(themePath), '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 */ }
+    }
+  }
+}
+
+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);
+
+  // 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/discover.ts

@@ -0,0 +1,151 @@
+/**
+ * `fragments discover` — list and filter components from fragments.json.
+ *
+ * Loads the compiled output and provides listing, search, category
+ * filtering, and status filtering. Outputs a formatted table, compact
+ * names list, or JSON depending on flags.
+ *
+ * This is the LIST mode only — semantic/useCase search requires the
+ * Orama sidecar available via the MCP server.
+ */
+
+import pc from 'picocolors';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type { CompiledFragmentsFile } from '../core/index.js';
+import { BRAND } from '../core/index.js';
+import { loadConfig } from '../core/node.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface DiscoverCommandOptions {
+  config?: string;
+  search?: string;
+  category?: string;
+  status?: string;
+  compact?: boolean;
+  json?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Command implementation
+// ---------------------------------------------------------------------------
+
+export async function discover(options: DiscoverCommandOptions): Promise<void> {
+  const { config, configDir } = await loadConfig(options.config);
+  const outputPath = resolve(configDir, config.outFile ?? BRAND.outFile);
+
+  let data: CompiledFragmentsFile;
+  try {
+    const content = await readFile(outputPath, 'utf-8');
+    data = JSON.parse(content) as CompiledFragmentsFile;
+  } catch {
+    console.error(
+      pc.red(`Error: Could not load ${BRAND.outFile}. Run \`${BRAND.cliCommand} build\` first.`),
+    );
+    process.exit(1);
+  }
+
+  let fragments = Object.values(data.fragments);
+
+  // --- Search filter (name, description, tags) ---
+  if (options.search) {
+    const term = options.search.toLowerCase();
+    fragments = fragments.filter(
+      (f) =>
+        f.meta.name.toLowerCase().includes(term) ||
+        f.meta.description?.toLowerCase().includes(term) ||
+        f.meta.tags?.some((t) => t.toLowerCase().includes(term)),
+    );
+  }
+
+  // --- Category filter ---
+  if (options.category) {
+    const cat = options.category.trim().toLowerCase();
+    fragments = fragments.filter(
+      (f) => f.meta.category?.toLowerCase() === cat,
+    );
+  }
+
+  // --- Status filter ---
+  if (options.status) {
+    const status = options.status.trim().toLowerCase();
+    fragments = fragments.filter((f) => (f.meta.status ?? 'stable') === status);
+  }
+
+  // Sort alphabetically
+  fragments.sort((a, b) => a.meta.name.localeCompare(b.meta.name));
+
+  const categories = [...new Set(fragments.map((f) => f.meta.category).filter(Boolean))].sort();
+
+  // --- JSON output ---
+  if (options.json) {
+    const output = {
+      total: fragments.length,
+      fragments: fragments.map((f) => ({
+        name: f.meta.name,
+        category: f.meta.category,
+        status: f.meta.status ?? 'stable',
+        description: f.meta.description,
+        tags: f.meta.tags,
+        variantCount: f.variants.length,
+        propCount: Object.keys(f.props ?? {}).length,
+      })),
+      categories,
+    };
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
+  // --- Compact output (names only) ---
+  if (options.compact) {
+    for (const f of fragments) {
+      console.log(f.meta.name);
+    }
+    return;
+  }
+
+  // --- Table output ---
+  if (fragments.length === 0) {
+    console.log(pc.yellow('\nNo components found matching the given filters.\n'));
+    return;
+  }
+
+  console.log(pc.bold(`\n${BRAND.name} Components (${fragments.length})\n`));
+
+  console.log(
+    pc.dim(
+      `  ${'Name'.padEnd(28)} ${'Category'.padEnd(16)} ${'Status'.padEnd(14)} ${'Variants'.padEnd(10)} ${'Props'}`,
+    ),
+  );
+  console.log(pc.dim(`  ${'─'.repeat(80)}`));
+
+  for (const f of fragments) {
+    const name = f.meta.name.length > 26 ? f.meta.name.slice(0, 23) + '...' : f.meta.name;
+    const category = (f.meta.category ?? '').padEnd(16);
+    const status = f.meta.status ?? 'stable';
+    const statusColored =
+      status === 'stable' ? pc.green(status.padEnd(14)) :
+      status === 'deprecated' ? pc.red(status.padEnd(14)) :
+      status === 'beta' ? pc.yellow(status.padEnd(14)) :
+      pc.cyan(status.padEnd(14));
+    const variantCount = String(f.variants.length).padEnd(10);
+    const propCount = String(Object.keys(f.props ?? {}).length);
+
+    console.log(
+      `  ${pc.cyan(name.padEnd(28))} ${pc.dim(category)} ${statusColored} ${variantCount} ${propCount}`,
+    );
+  }
+
+  // Summary
+  console.log(pc.dim(`\n  ${'─'.repeat(80)}`));
+  console.log(
+    pc.dim(`  ${fragments.length} component(s) across ${categories.length} categories`),
+  );
+  if (categories.length > 0) {
+    console.log(pc.dim(`  Categories: ${categories.join(', ')}`));
+  }
+  console.log();
+}

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'];