@fragments-sdk/cli 0.9.0 → 0.10.0

package/src/commands/init.ts

@@ -1,10 +1,11 @@
 /**
  * fragments init - Smart interactive initialization
  *
- * Handles three scenarios:
- * 1. Stories found → Configure and load existing stories
- * 2. Components found (no stories) → Auto-generate documentation
- * 3. Fresh project → Guided setup with example component
+ * 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
  */
 
 import { readFile, writeFile, mkdir, access } from "node:fs/promises";
@@ -29,12 +30,14 @@ export interface InitOptions {
   yes?: boolean;
   /** Explicit framework override */
   framework?: string;
+  /** Path to scan for components (enables scan mode) */
+  scan?: string;
 }
 
 export interface InitResult {
   success: boolean;
   configPath?: string;
-  scenario: "stories" | "components" | "fresh";
+  scenario: "stories" | "components" | "fresh" | "scan";
   storiesFound: number;
   componentsFound: number;
   errors: string[];
@@ -396,6 +399,70 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
   const projectRoot = resolve(options.projectRoot || process.cwd());
   const errors: string[] = [];
 
+  // Early return for scan mode — non-interactive
+  if (options.scan) {
+    const scanPath = resolve(projectRoot, options.scan);
+
+    // Verify scan path exists
+    try {
+      await access(scanPath);
+    } catch {
+      console.error(pc.red(`\nScan path not found: ${scanPath}\n`));
+      return {
+        success: false,
+        scenario: "scan",
+        storiesFound: 0,
+        componentsFound: 0,
+        errors: [`Scan path not found: ${scanPath}`],
+      };
+    }
+
+    // Run scan-generate
+    const { scanGenerate } = await import("./scan-generate.js");
+    const scanResult = await scanGenerate({
+      scanPath,
+      force: options.force,
+      verbose: true,
+    });
+
+    // Create config pointing at the scanned path
+    const relScanPath = relative(projectRoot, scanPath);
+    const configPath = join(projectRoot, BRAND.configFile);
+    const configContent = generateConfig({
+      includePaths: [`${relScanPath}/**/*.fragment.tsx`],
+      componentPaths: [`${relScanPath}/**/*.tsx`],
+      framework: "react",
+    });
+
+    try {
+      await writeFile(configPath, configContent, "utf-8");
+      console.log(pc.green(`✓ Created ${BRAND.configFile}`));
+    } catch (e) {
+      errors.push(`Failed to create config: ${e}`);
+    }
+
+    // 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`);
+      console.log();
+    }
+
+    return {
+      success: scanResult.success && errors.length === 0,
+      configPath: errors.length === 0 ? configPath : undefined,
+      scenario: "scan",
+      storiesFound: 0,
+      componentsFound: scanResult.generated.length,
+      errors: [
+        ...errors,
+        ...scanResult.errors.map((e) => `${e.name}: ${e.error}`),
+      ],
+    };
+  }
+
   console.log(pc.cyan(`\n✨ Welcome to ${BRAND.name}!\n`));
 
   // Step 1: Detect what exists
@@ -462,9 +529,9 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
 
   // Step 3: Gather configuration (interactive unless --yes)
   let componentPath = detection.suggestedComponentPath;
-  let runScan = scenario === "components";
+  let runScan = scenario === "components" || scenario === "stories";
   let createExample = scenario === "fresh";
-  let startServer = true;
+  let startServer = false;
 
   if (!options.yes) {
     // Ask about component location
@@ -473,13 +540,7 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
       default: detection.suggestedComponentPath,
     });
 
-    if (scenario === "components") {
-      // For component-only projects, ask about scanning
-      runScan = await confirm({
-        message: "Auto-generate documentation from TypeScript?",
-        default: true,
-      });
-    } else {
+    if (scenario === "fresh") {
       // Fresh project - ask about example
       createExample = await confirm({
         message: "Create an example Button component to get started?",
@@ -502,7 +563,7 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
     `${componentPath}/**/*.fragment.tsx`,
   ];
 
-  // Include story files when Storybook is detected
+  // If Storybook stories detected, also include them for direct rendering
   if (scenario === 'stories') {
     includePaths.push(`${componentPath}/**/*.stories.tsx`);
     includePaths.push(`${componentPath}/**/*.stories.ts`);
@@ -557,39 +618,9 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
     }
   }
 
-  if (scenario === "components" && runScan) {
-    // Generate .fragment.tsx stubs for discovered components
-    let stubsCreated = 0;
-    for (const compFile of detection.componentFiles) {
-      const absPath = join(projectRoot, compFile);
-      const dir = dirname(absPath);
-      const fileName = basename(compFile, ".tsx");
-      const componentName = toPascalCase(fileName);
-      const fragmentPath = join(dir, `${fileName}.fragment.tsx`);
-
-      // Skip if fragment already exists
-      try {
-        await access(fragmentPath);
-        continue; // already exists
-      } catch {
-        // doesn't exist, create it
-      }
-
-      try {
-        const stub = generateFragmentStub(componentName, `./${fileName}`);
-        await writeFile(fragmentPath, stub, "utf-8");
-        stubsCreated++;
-      } catch {
-        // skip files we can't write to
-      }
-    }
-
-    if (stubsCreated > 0) {
-      console.log(pc.green(`✓ Generated ${stubsCreated} fragment stub(s)`));
-    }
-
-    // Run scan to generate fragments.json
-    console.log(pc.dim("\nGenerating documentation from source code...\n"));
+  if (runScan) {
+    // Run scan to generate fragments.json from source code
+    console.log(pc.dim("\nScanning source code for documentation...\n"));
     try {
       const { scan } = await import("./scan.js");
       await scan({
@@ -641,14 +672,7 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
     console.log(pc.green("\n✓ Setup complete!\n"));
 
     if (startServer) {
-      const serverMessage =
-        scenario === "stories"
-          ? `Your ${detection.storyFiles.length} stories are loading...`
-          : scenario === "components"
-          ? `Your ${detection.componentFiles.length} components are being documented...`
-          : `Your first component is ready!`;
-
-      console.log(pc.cyan(serverMessage));
+      console.log(pc.cyan("Starting viewer...\n"));
       startDevServer(projectRoot);
     } else {
       console.log(pc.cyan("Next steps:"));
@@ -656,6 +680,7 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
       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();
     }
   }

package/src/commands/perf.ts

@@ -16,7 +16,7 @@ import {
   budgetBar,
   type PerformanceConfig,
   type ComplexityTier,
-} from '../core/performance-presets.js';
+} from '../core/index.js';
 import {
   measureBundleSizes,
   toPerformanceData,