@fragments-sdk/cli 0.10.1 → 0.12.1

package/src/commands/init.ts

@@ -1,37 +1,48 @@
 /**
- * fragments init - Smart interactive initialization
+ * fragments init - Zero-config project initialization
  *
- * Handles four scenarios:
- * 1. --scan <path> → Scan external component library, generate fragment files
- * 2. Stories found → Configure and load existing stories
- * 3. Components found (no stories) → Auto-generate documentation
- * 4. Fresh project → Guided setup with example component
+ * Default: auto-detect everything, zero prompts, instant setup.
+ * --configure: interactive mode for theme seeds, snapshots, etc.
+ * --scan <path>: scan external component library, generate fragment files.
  */
 
 import { readFile, writeFile, mkdir, access } from "node:fs/promises";
-import { resolve, join, relative, dirname, basename } from "node:path";
+import { resolve, join, relative } from "node:path";
 import { spawn } from "node:child_process";
 import pc from "picocolors";
 import { BRAND } from "../core/index.js";
 import fg from "fast-glob";
-import { input, confirm, select } from "@inquirer/prompts";
 import {
-  setupFramework,
-  detectFramework,
-  type Framework,
-} from "./init-framework.js";
+  detectSetupFramework,
+  findEntryFile,
+  addStylesImport,
+  addThemeProvider,
+  addTranspilePackages,
+} from "./setup.js";
 
 export interface InitOptions {
   /** Project root directory */
   projectRoot?: string;
   /** Force overwrite existing config */
   force?: boolean;
-  /** Non-interactive mode - auto-detect and use defaults */
+  /** Non-interactive mode - auto-detect and use defaults (legacy, now the default behavior) */
   yes?: boolean;
   /** Explicit framework override */
   framework?: string;
   /** Path to scan for components (enables scan mode) */
   scan?: string;
+  /** Enable interactive configuration (theme seeds, snapshots, etc.) */
+  configure?: boolean;
+  /** Use AI to fill knowledge fields during --scan */
+  enrich?: boolean;
+  /** Show what --enrich would generate without calling API */
+  dryRun?: boolean;
+  /** AI provider for enrichment: anthropic or openai */
+  provider?: 'anthropic' | 'openai';
+  /** API key for AI enrichment */
+  apiKey?: string;
+  /** Override AI model for enrichment */
+  model?: string;
 }
 
 export interface InitResult {
@@ -49,14 +60,13 @@ interface DetectionResult {
   hasConfig: boolean;
   configPath: string | null;
   suggestedComponentPath: string;
+  scenario: "stories" | "components" | "fresh";
 }
 
 /**
  * Detect what exists in the project
  */
 async function detectProject(projectRoot: string): Promise<DetectionResult> {
-  console.log(pc.dim("\nScanning project...\n"));
-
   // Check for existing config
   const configPath = join(projectRoot, BRAND.configFile);
   const legacyConfigPath = join(projectRoot, BRAND.legacyConfigFile);
@@ -127,12 +137,16 @@ async function detectProject(projectRoot: string): Promise<DetectionResult> {
     }
   }
 
+  const scenario: DetectionResult["scenario"] =
+    storyFiles.length > 0 ? "stories" : likelyComponents.length > 0 ? "components" : "fresh";
+
   return {
     storyFiles,
     componentFiles: likelyComponents,
     hasConfig,
     configPath: foundConfigPath,
     suggestedComponentPath,
+    scenario,
   };
 }
 
@@ -143,6 +157,8 @@ function generateConfig(options: {
   includePaths: string[];
   componentPaths: string[];
   framework: string;
+  themeBlock?: string;
+  snapshotsBlock?: string;
 }): string {
   const includeStr = options.includePaths.map((p) => `    '${p}'`).join(",\n");
   const componentStr = options.componentPaths.map((p) => `    '${p}'`).join(",\n");
@@ -165,7 +181,7 @@ ${componentStr}
 
   // Framework (react, vue, svelte)
   framework: '${options.framework}',
-};
+${options.themeBlock || ""}${options.snapshotsBlock || ""}};
 
 export default config;
 `;
@@ -326,52 +342,6 @@ export default defineFragment({
 `;
 }
 
-/**
- * Convert a filename to PascalCase component name
- */
-function toPascalCase(str: string): string {
-  return str
-    .replace(/[-_.](\w)/g, (_, c) => c.toUpperCase())
-    .replace(/^\w/, (c) => c.toUpperCase());
-}
-
-/**
- * Generate a minimal fragment stub for a discovered component
- */
-function generateFragmentStub(componentName: string, importPath: string): string {
-  return `import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
-import { ${componentName} } from '${importPath}';
-
-export default defineFragment({
-  component: ${componentName},
-
-  meta: {
-    name: '${componentName}',
-    description: '${componentName} component',
-    category: 'general',
-    status: 'beta',
-  },
-
-  usage: {
-    when: ['TODO: describe when to use ${componentName}'],
-    whenNot: ['TODO: describe when not to use ${componentName}'],
-  },
-
-  props: {},
-
-  variants: [
-    {
-      name: 'Default',
-      description: 'Default ${componentName}',
-      code: \`<${componentName} />\`,
-      render: () => <${componentName} />,
-    },
-  ],
-});
-`;
-}
-
 /**
  * Start the dev server
  */
@@ -393,7 +363,142 @@ function startDevServer(projectRoot: string): void {
 }
 
 /**
- * Main init function - smart and interactive by default
+ * Map init-framework's Framework type to setup's Framework type
+ */
+function mapFrameworkLabel(framework: string): string {
+  const labels: Record<string, string> = {
+    "nextjs-app": "Next.js (App Router)",
+    "nextjs-pages": "Next.js (Pages Router)",
+    "vite": "Vite",
+    "remix": "Remix",
+    "astro": "Astro",
+  };
+  return labels[framework] || "Unknown";
+}
+
+// ============================================
+// Interactive configuration (--configure)
+// ============================================
+
+interface ConfigureResult {
+  componentPath: string;
+  createExample: boolean;
+  startServer: boolean;
+  themeBlock: string;
+  snapshotsBlock: string;
+}
+
+async function runInteractiveConfigure(
+  detection: DetectionResult,
+  scenario: "stories" | "components" | "fresh"
+): Promise<ConfigureResult> {
+  const { input, confirm, select } = await import("@inquirer/prompts");
+
+  const componentPath = await input({
+    message: "Where are your components located?",
+    default: detection.suggestedComponentPath,
+  });
+
+  let createExample = scenario === "fresh";
+  if (scenario === "fresh") {
+    createExample = await confirm({
+      message: "Create an example Button component to get started?",
+      default: true,
+    });
+  }
+
+  // Theme seed configuration
+  let themeBlock = "";
+  const configureTheme = await confirm({
+    message: "Configure theme seeds? (brand color, density, radius)",
+    default: false,
+  });
+
+  if (configureTheme) {
+    const brand = await input({
+      message: "Brand color (hex)",
+      default: "#18181b",
+      validate: (v) => /^#[0-9a-fA-F]{6}$/.test(v) || "Enter a valid hex color (e.g., #6366f1)",
+    });
+
+    const neutral = await select({
+      message: "Neutral palette",
+      choices: [
+        { value: "stone", name: "Stone (warm gray)" },
+        { value: "ice", name: "Ice (cool blue-gray)" },
+        { value: "earth", name: "Earth (olive/khaki)" },
+        { value: "sand", name: "Sand (warm beige)" },
+        { value: "fire", name: "Fire (warm red-gray)" },
+      ],
+      default: "stone",
+    });
+
+    const density = await select({
+      message: "Spacing density",
+      choices: [
+        { value: "compact", name: "Compact (tighter spacing)" },
+        { value: "default", name: "Default" },
+        { value: "relaxed", name: "Relaxed (more breathing room)" },
+      ],
+      default: "default",
+    });
+
+    const radiusStyle = await select({
+      message: "Border radius style",
+      choices: [
+        { value: "sharp", name: "Sharp (0px)" },
+        { value: "subtle", name: "Subtle (2px)" },
+        { value: "default", name: "Default (6px)" },
+        { value: "rounded", name: "Rounded (10px)" },
+        { value: "pill", name: "Pill (999px)" },
+      ],
+      default: "default",
+    });
+
+    // Build theme config block — only include non-default values
+    const themeEntries: string[] = [];
+    if (brand !== "#18181b") themeEntries.push(`    brand: '${brand}'`);
+    if (neutral !== "stone") themeEntries.push(`    neutral: '${neutral}'`);
+    if (density !== "default") themeEntries.push(`    density: '${density}'`);
+    if (radiusStyle !== "default") themeEntries.push(`    radiusStyle: '${radiusStyle}'`);
+
+    if (themeEntries.length > 0) {
+      themeBlock = `\n  // Theme seed values (derives 120+ CSS custom properties)\n  theme: {\n${themeEntries.join(",\n")},\n  },\n`;
+    }
+  }
+
+  // Snapshot toggle
+  let snapshotsBlock = "";
+  const enableSnapshots = await confirm({
+    message: "Enable visual snapshot tests per component variant?",
+    default: false,
+  });
+
+  if (enableSnapshots) {
+    snapshotsBlock = `\n  // Visual snapshot testing\n  snapshots: {\n    enabled: true,\n  },\n`;
+  }
+
+  // Ask about starting the server
+  const startServer = await confirm({
+    message: "Start the viewer now?",
+    default: true,
+  });
+
+  return {
+    componentPath,
+    createExample,
+    startServer,
+    themeBlock,
+    snapshotsBlock,
+  };
+}
+
+// ============================================
+// Main init function
+// ============================================
+
+/**
+ * Main init function - zero-config by default, interactive with --configure
  */
 export async function init(options: InitOptions = {}): Promise<InitResult> {
   const projectRoot = resolve(options.projectRoot || process.cwd());
@@ -423,6 +528,11 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
       scanPath,
       force: options.force,
       verbose: true,
+      enrich: options.enrich,
+      dryRun: options.dryRun,
+      provider: options.provider,
+      apiKey: options.apiKey,
+      model: options.model,
     });
 
     // Create config pointing at the scanned path
@@ -444,9 +554,16 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
     // Next steps
     if (scanResult.success) {
       console.log(pc.cyan("Next steps:"));
-      console.log(`  1. Search generated files for ${pc.bold("TODO:")} markers and fill in human knowledge`);
-      console.log(`  2. Run ${pc.bold(`${BRAND.cliCommand} dev`)} to preview your components`);
-      console.log(`  3. Run ${pc.bold(`${BRAND.cliCommand} build`)} to compile fragments.json`);
+      if (options.enrich && !options.dryRun) {
+        console.log(`  1. Review AI-enriched fields (usage.when, a11yRules, scenarioTags) in generated files`);
+        if (scanResult.generated.some(g => g.todoCount > 0)) {
+          console.log(`  2. Search remaining ${pc.bold("TODO:")} markers and fill in human knowledge`);
+        }
+      } else {
+        console.log(`  1. Search generated files for ${pc.bold("TODO:")} markers and fill in human knowledge`);
+      }
+      console.log(`  ${options.enrich ? '3' : '2'}. Run ${pc.bold(`${BRAND.cliCommand} dev`)} to preview your components`);
+      console.log(`  ${options.enrich ? '4' : '3'}. Run ${pc.bold(`${BRAND.cliCommand} build`)} to compile fragments.json`);
       console.log();
     }
 
@@ -463,146 +580,152 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
     };
   }
 
-  console.log(pc.cyan(`\n✨ Welcome to ${BRAND.name}!\n`));
+  console.log(pc.cyan(`\n${BRAND.name} init\n`));
 
   // Step 1: Detect what exists
   const detection = await detectProject(projectRoot);
 
   // Check for existing config
   if (detection.hasConfig && !options.force) {
-    console.log(pc.yellow(`⚠ Config already exists: ${BRAND.configFile}`));
-
-    if (!options.yes) {
-      const overwrite = await confirm({
-        message: "Do you want to reinitialize? (This will overwrite your config)",
-        default: false,
-      });
-
-      if (!overwrite) {
-        console.log(pc.dim(`\nKeeping existing configuration. Run \`${BRAND.cliCommand} dev\` to start.\n`));
-        return {
-          success: true,
-          scenario: "stories",
-          storiesFound: detection.storyFiles.length,
-          componentsFound: detection.componentFiles.length,
-          errors: [],
-        };
-      }
+    if (options.configure) {
+      // In configure mode, warn but continue
+      console.log(pc.yellow(`  ! Config exists: ${BRAND.configFile} (will overwrite)`));
+    } else {
+      console.log(pc.green(`  ✓ Already initialized`) + pc.dim(` (${BRAND.configFile} exists)`));
+      console.log();
+      console.log(pc.dim(`  Run ${pc.bold(`${BRAND.cliCommand} init --force`)} to reinitialize`));
+      console.log(pc.dim(`  Run ${pc.bold(`${BRAND.cliCommand} init --configure`)} to customize theme, snapshots, etc.`));
+      console.log();
+      return {
+        success: true,
+        scenario: detection.scenario,
+        storiesFound: detection.storyFiles.length,
+        componentsFound: detection.componentFiles.length,
+        errors: [],
+      };
     }
   }
 
-  // Step 2: Determine scenario and show what we found
+  // Step 2: Determine scenario
   let scenario: "stories" | "components" | "fresh";
 
   if (detection.storyFiles.length > 0) {
     scenario = "stories";
-    console.log(pc.green(`✓ Found ${detection.storyFiles.length} Storybook story file(s)`));
-    console.log(pc.dim(`  ${detection.storyFiles.slice(0, 3).join("\n  ")}`));
-    if (detection.storyFiles.length > 3) {
-      console.log(pc.dim(`  ... and ${detection.storyFiles.length - 3} more`));
-    }
-    console.log();
-    console.log(
-      pc.cyan("Great news! ") +
-        "Fragments can load your existing stories automatically."
-    );
+    console.log(pc.green(`  ✓ Found ${detection.storyFiles.length} Storybook stories`));
   } else if (detection.componentFiles.length > 0) {
     scenario = "components";
-    console.log(pc.green(`✓ Found ${detection.componentFiles.length} component file(s)`));
-    console.log(pc.dim(`  ${detection.componentFiles.slice(0, 3).join("\n  ")}`));
-    if (detection.componentFiles.length > 3) {
-      console.log(pc.dim(`  ... and ${detection.componentFiles.length - 3} more`));
-    }
-    console.log();
-    console.log(
-      pc.cyan("No stories found, but that's fine! ") +
-        "Fragments can auto-generate documentation from your TypeScript."
-    );
+    console.log(pc.green(`  ✓ Found ${detection.componentFiles.length} components`) + pc.dim(` in ${detection.suggestedComponentPath}`));
   } else {
     scenario = "fresh";
-    console.log(pc.yellow("No components or stories found."));
-    console.log();
-    console.log(pc.cyan("Let's create your first fragment!"));
+    console.log(pc.dim(`  · No existing components found`));
   }
 
-  console.log();
+  // Step 3: Detect framework
+  const framework = await detectSetupFramework(projectRoot);
+  console.log(pc.green(`  ✓ Detected ${mapFrameworkLabel(framework)}`));
 
-  // Step 3: Gather configuration (interactive unless --yes)
+  // Step 4: Branch — interactive configure or fast path
   let componentPath = detection.suggestedComponentPath;
-  let runScan = scenario === "components" || scenario === "stories";
   let createExample = scenario === "fresh";
   let startServer = false;
-
-  if (!options.yes) {
-    // Ask about component location
-    componentPath = await input({
-      message: "Where are your components located?",
-      default: detection.suggestedComponentPath,
-    });
-
-    if (scenario === "fresh") {
-      // Fresh project - ask about example
-      createExample = await confirm({
-        message: "Create an example Button component to get started?",
-        default: true,
-      });
-    }
-
-    // Ask about starting the server
-    startServer = await confirm({
-      message: "Start the viewer now?",
-      default: true,
-    });
+  let themeBlock = "";
+  let snapshotsBlock = "";
+
+  if (options.configure) {
+    const config = await runInteractiveConfigure(detection, scenario);
+    componentPath = config.componentPath;
+    createExample = config.createExample;
+    startServer = config.startServer;
+    themeBlock = config.themeBlock;
+    snapshotsBlock = config.snapshotsBlock;
   }
 
-  // Step 4: Create configuration
-  console.log(pc.dim("\nCreating configuration...\n"));
-
-  // Build include patterns
+  // Step 5: Create configuration file
   const includePaths: string[] = [
     `${componentPath}/**/*.fragment.tsx`,
   ];
 
-  // If Storybook stories detected, also include them for direct rendering
   if (scenario === 'stories') {
     includePaths.push(`${componentPath}/**/*.stories.tsx`);
     includePaths.push(`${componentPath}/**/*.stories.ts`);
   }
 
-  // Create config file
   const configPath = join(projectRoot, BRAND.configFile);
   const configContent = generateConfig({
     includePaths,
     componentPaths: [`${componentPath}/**/*.tsx`],
     framework: "react",
+    themeBlock,
+    snapshotsBlock,
   });
 
   try {
     await writeFile(configPath, configContent, "utf-8");
-    console.log(pc.green(`✓ Created ${BRAND.configFile}`));
+    console.log(pc.green(`  ✓ Created ${BRAND.configFile}`));
   } catch (e) {
     errors.push(`Failed to create config: ${e}`);
   }
 
-  // Step 5: Handle scenario-specific setup
+  // Step 6: Auto-inject styles + framework config
+  const entryFile = await findEntryFile(projectRoot, framework);
+
+  if (entryFile) {
+    try {
+      const stylesResult = await addStylesImport(projectRoot, entryFile);
+      if (stylesResult.modified) {
+        console.log(pc.green(`  ✓ Added styles import to ${entryFile}`));
+      } else {
+        console.log(pc.dim(`  · ${stylesResult.message}`));
+      }
+    } catch (e) {
+      errors.push(`Failed to add styles import: ${e instanceof Error ? e.message : e}`);
+    }
+
+    try {
+      const providerResult = await addThemeProvider(projectRoot, entryFile, framework);
+      if (providerResult.modified) {
+        console.log(pc.green(`  ✓ Added ThemeProvider to ${entryFile}`));
+      } else {
+        console.log(pc.dim(`  · ${providerResult.message}`));
+      }
+    } catch (e) {
+      errors.push(`Failed to add ThemeProvider: ${e instanceof Error ? e.message : e}`);
+    }
+  } else {
+    console.log(pc.yellow(`  ! Could not detect entry file — add styles import manually`));
+    console.log(pc.dim(`    import '@fragments-sdk/ui/styles'`));
+  }
+
+  // Next.js: add transpilePackages
+  if (framework === 'nextjs-app' || framework === 'nextjs-pages') {
+    try {
+      const transpileResult = await addTranspilePackages(projectRoot);
+      if (transpileResult.modified) {
+        console.log(pc.green(`  ✓ ${transpileResult.message}`));
+      } else {
+        console.log(pc.dim(`  · ${transpileResult.message}`));
+      }
+    } catch (e) {
+      errors.push(`Failed to update next.config: ${e instanceof Error ? e.message : e}`);
+    }
+  }
+
+  // Step 7: Handle scenario-specific setup
   if (scenario === "fresh" && createExample) {
-    // Create example component
     const exampleDir = join(projectRoot, componentPath, "Button");
 
     try {
       await mkdir(exampleDir, { recursive: true });
 
-      // Write Button.tsx
       await writeFile(
         join(exampleDir, "Button.tsx"),
         generateExampleComponent(),
         "utf-8"
       );
       console.log(
-        pc.green(`✓ Created ${relative(projectRoot, join(exampleDir, "Button.tsx"))}`)
+        pc.green(`  ✓ Created ${relative(projectRoot, join(exampleDir, "Button.tsx"))}`)
       );
 
-      // Write Button.fragment.tsx
       await writeFile(
         join(exampleDir, "Button.fragment.tsx"),
         generateExampleFragment(),
@@ -610,7 +733,7 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
       );
       console.log(
         pc.green(
-          `✓ Created ${relative(projectRoot, join(exampleDir, "Button.fragment.tsx"))}`
+          `  ✓ Created ${relative(projectRoot, join(exampleDir, "Button.fragment.tsx"))}`
         )
       );
     } catch (e) {
@@ -618,70 +741,50 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
     }
   }
 
-  if (runScan) {
-    // Run scan to generate fragments.json from source code
-    console.log(pc.dim("\nScanning source code for documentation...\n"));
+  if (scenario === "components" || scenario === "stories") {
     try {
       const { scan } = await import("./scan.js");
-      await scan({
+      const scanResult = await scan({
         config: configPath,
         verbose: false,
+        quiet: true,
       });
-    } catch (e) {
+      if (scanResult.success) {
+        console.log(pc.green(`  ✓ Generated fragments.json`) + pc.dim(` (${scanResult.componentCount} components)`));
+      } else {
+        console.log(pc.dim(`  · Auto-documentation will run when you start the dev server`));
+      }
+    } catch {
       console.log(
-        pc.yellow(`Note: Auto-documentation will run when you start the dev server.`)
+        pc.dim(`  · Auto-documentation will run when you start the dev server`)
       );
     }
   }
 
-  // Step 6: Framework-specific configuration
-  console.log(pc.dim("\nConfiguring framework integration...\n"));
-
-  const frameworkOverride = options.framework as Framework | undefined;
-  const frameworkResult = await setupFramework({
-    projectRoot,
-    framework: frameworkOverride,
-  });
-
-  if (frameworkResult.filesCreated.length > 0) {
-    for (const file of frameworkResult.filesCreated) {
-      console.log(pc.green(`✓ Created ${file}`));
-    }
-  }
+  // Step 8: Summary
+  console.log();
 
-  if (frameworkResult.configModified.length > 0) {
-    for (const file of frameworkResult.configModified) {
-      console.log(pc.green(`✓ Updated ${file}`));
+  if (errors.length > 0) {
+    console.log(pc.red(`  ${errors.length} error(s) occurred:`));
+    for (const error of errors) {
+      console.log(pc.red(`    - ${error}`));
     }
-  }
-
-  if (frameworkResult.packagesToInstall.length > 0) {
-    const pkgs = frameworkResult.packagesToInstall.join(" ");
-    console.log(
-      pc.yellow(`\n⚠ Install required dependencies: `) +
-        pc.bold(`pnpm add -D ${pkgs}`)
-    );
-  }
-
-  for (const warning of frameworkResult.warnings) {
-    console.log(pc.yellow(`  Note: ${warning}`));
-  }
-
-  // Step 7: Show next steps or start server
-  if (errors.length === 0) {
-    console.log(pc.green("\n✓ Setup complete!\n"));
+    console.log();
+  } else {
+    console.log(pc.green(`  Done!`) + pc.dim(` Setup complete.\n`));
 
     if (startServer) {
-      console.log(pc.cyan("Starting viewer...\n"));
       startDevServer(projectRoot);
     } else {
-      console.log(pc.cyan("Next steps:"));
-      console.log(`  1. Run ${pc.bold(`${BRAND.cliCommand} dev`)} to start the viewer`);
-      if (scenario === "fresh") {
-        console.log(`  2. Edit ${pc.bold(`${componentPath}/Button/Button.fragment.tsx`)}`);
-      }
-      console.log(`  3. Run ${pc.bold(`${BRAND.cliCommand} generate`)} to create fragment files for your components`);
+      console.log(`  ${pc.bold("Get started:")}`);
+      console.log(`    ${pc.dim("$")} ${BRAND.cliCommand} dev`);
       console.log();
+
+      if (!options.configure) {
+        console.log(`  ${pc.bold("Customize:")} theme seeds, snapshots, and more`);
+        console.log(`    ${pc.dim("$")} ${BRAND.cliCommand} init --configure`);
+        console.log();
+      }
     }
   }