@fragments-sdk/cli 0.9.0 → 0.10.0

package/src/core/index.ts

@@ -1,192 +1,5 @@
 /**
- * Browser-safe exports for @fragments-sdk/cli/core
- * For Node.js-only APIs (config, discovery, loader), import from '@fragments-sdk/cli' directly.
+ * @deprecated Import from '@fragments-sdk/core' directly.
+ * This re-export exists for backwards compatibility with '@fragments-sdk/cli/core'.
  */
-
-// Brand and default constants
-export { BRAND, DEFAULTS } from "./constants.js";
-export type { Brand, Defaults } from "./constants.js";
-
-// Types
-export type {
-  FragmentComponent,
-  FragmentMeta,
-  FragmentUsage,
-  PropType,
-  PropDefinition,
-  ControlType,
-  RelationshipType,
-  ComponentRelation,
-  VariantLoader,
-  PlayFunction,
-  PlayFunctionContext,
-  FragmentVariant,
-  FragmentDefinition,
-  FragmentsConfig,
-  SnippetPolicyConfig,
-  RegistryOptions,
-  CompiledFragment,
-  CompiledFragmentsFile,
-  BlockDefinition,
-  CompiledBlock,
-  RecipeDefinition, // @deprecated - use BlockDefinition
-  CompiledRecipe, // @deprecated - use CompiledBlock
-  // Contract and provenance types
-  FragmentContract,
-  FragmentGenerated,
-  // AI metadata type
-  AIMetadata,
-  // Screenshot types
-  ScreenshotConfig,
-  ServiceConfig,
-  Viewport,
-  Theme,
-  Screenshot,
-  ScreenshotMetadata,
-  DiffResult,
-  BoundingBox,
-  BaselineInfo,
-  Manifest,
-  VerifyRequest,
-  VerifyResult,
-  // Figma property mapping types
-  FigmaPropMapping,
-  FigmaStringMapping,
-  FigmaBooleanMapping,
-  FigmaEnumMapping,
-  FigmaInstanceMapping,
-  FigmaChildrenMapping,
-  FigmaTextContentMapping,
-  // Token configuration
-  TokenConfig,
-  // Compiled token types
-  CompiledTokenEntry,
-  CompiledTokenData,
-} from "./types.js";
-
-// Performance presets
-export {
-  resolvePerformanceConfig,
-  classifyComplexity,
-  formatBytes,
-  budgetBar,
-  PRESET_NAMES,
-} from "./performance-presets.js";
-export type {
-  PerformanceBudgets,
-  PerformanceConfig,
-  ComplexityTier,
-  PerformanceData as PerfData,
-  PerformanceSummary as PerfSummary,
-} from "./performance-presets.js";
-
-// Token types
-export type {
-  TokenCategory,
-  DesignToken,
-  TokenRegistry,
-  TokenRegistryMeta,
-  EnhancedStyleDiffItem,
-  TokenFix,
-  TokenParseResult,
-  TokenParseError,
-  TokenMatchRequest,
-  TokenMatchResult,
-  TokenUsageSummary,
-} from "./token-types.js";
-
-// Schema validation (Zod is browser-safe)
-export {
-  fragmentMetaSchema,
-  fragmentUsageSchema,
-  propDefinitionSchema,
-  componentRelationSchema,
-  fragmentVariantSchema,
-  fragmentDefinitionSchema,
-  fragmentsConfigSchema,
-  figmaPropMappingSchema,
-  // Contract and provenance schemas
-  fragmentContractSchema,
-  fragmentGeneratedSchema,
-  fragmentBanSchema,
-  blockDefinitionSchema,
-  recipeDefinitionSchema, // @deprecated - use blockDefinitionSchema
-  // AI metadata schema
-  aiMetadataSchema,
-} from "./schema.js";
-
-// Main API
-export { defineFragment, compileFragment, defineBlock, compileBlock, defineRecipe, compileRecipe } from "./defineFragment.js";
-export type { InferProps } from "./defineFragment.js";
-
-// Story adapter (runtime conversion of Storybook modules)
-export {
-  storyModuleToFragment,
-  setPreviewConfig,
-  getPreviewConfig,
-  // Re-export @storybook/csf utilities
-  toId,
-  storyNameFromExport,
-  isExportStory,
-} from "./storyAdapter.js";
-export type {
-  StoryModule,
-  StoryMeta,
-  Story,
-  StoryArgType,
-  StoryContext,
-  Decorator,
-  Loader,
-  PreviewConfig,
-  CSF2Story,
-} from "./storyAdapter.js";
-
-// Context generation for AI agents
-export { generateContext } from "./context.js";
-export type { ContextOptions, ContextResult } from "./context.js";
-
-// Figma property mapping DSL
-export { figma, isFigmaPropMapping, resolveFigmaMapping } from "./figma.js";
-
-// Fragment JSON types (for .fragment.json files)
-export type {
-  Fragment,
-  FragmentFigma,
-  FragmentUsage as FragmentJsonUsage,
-  FragmentDoNotItem,
-  FragmentPattern,
-  FragmentAccessibility,
-  FragmentRelated,
-  FragmentMeta as FragmentJsonMeta,
-  FragmentIndex,
-  FragmentRegistry,
-  RegistryComponentEntry,
-  RegistryPropEntry,
-  FragmentContextOptions,
-} from "./fragment-types.js";
-
-// Token parsing
-export { parseTokenFile } from "./token-parser.js";
-export type { ParsedToken, TokenParseOutput } from "./token-parser.js";
-
-// Composition analysis
-export { analyzeComposition } from "./composition.js";
-export type {
-  CompositionAnalysis,
-  CompositionWarning,
-  CompositionSuggestion,
-  CompositionGuideline,
-} from "./composition.js";
-
-// Shared preview runtime
-export {
-  executeVariantLoaders,
-  resolvePreviewRuntimeState,
-  usePreviewVariantRuntime,
-  PreviewVariantRuntime,
-} from "./preview-runtime.js";
-export type {
-  PreviewVariantLike,
-  PreviewRuntimeState,
-  PreviewRuntimeOptions,
-} from "./preview-runtime.js";
+export * from '@fragments-sdk/core';

package/src/core/loader.ts

@@ -2,8 +2,8 @@ import { writeFile, unlink } from 'node:fs/promises';
 import { dirname, basename, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { build, type Plugin } from 'esbuild';
-import type { FragmentDefinition } from './types.js';
-import { BRAND } from './constants.js';
+import { BRAND } from '@fragments-sdk/core';
+import type { FragmentDefinition } from '@fragments-sdk/core';
 
 // Inline implementation of defineFragment that will be injected into bundled files
 // This allows fragment files to work without @fragments/core being installed

package/src/core/parser.ts

@@ -8,7 +8,7 @@
  */
 
 import ts from "typescript";
-import type { FragmentMeta, FragmentUsage, PropDefinition, AIMetadata, FragmentContract } from "./types.js";
+import type { FragmentMeta, FragmentUsage, PropDefinition, AIMetadata, FragmentContract } from '@fragments-sdk/core';
 
 /**
  * Parsed fragment metadata (extracted statically from AST)

package/src/core/previewLoader.ts

@@ -12,7 +12,7 @@
 
 import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
-import type { PreviewConfig } from "./storyAdapter.js";
+import type { PreviewConfig } from '@fragments-sdk/core';
 
 /**
  * Possible file extensions and names for preview config

package/src/index.ts

@@ -44,10 +44,10 @@ export type { AnalyzeOptions, AnalyzeResult } from "./analyze.js";
 export { generateStaticViewer, generateViewerFromJson } from "./static-viewer.js";
 
 // Config type (used by generated fragments.config.ts)
-export type { FragmentsConfig } from "./core/types.js";
+export type { FragmentsConfig } from "./core/index.js";
 
 // Fragment definition API (used by generated .fragment.tsx files)
-export { defineFragment, defineBlock } from "./core/defineFragment.js";
+export { defineFragment, defineBlock } from "./core/index.js";
 
 // CLI Command metadata (for docs)
 export { CLI_COMMANDS, CLI_COMMAND_CATEGORIES } from "./cli-commands.js";

package/src/migrate/converter.ts

@@ -87,6 +87,7 @@ export function convertToFragment(parsed: ParsedStoryFile): ConversionResult {
   const code = generateFragmentCode({
     componentName,
     componentImport: parsed.meta.componentImport,
+    isDefaultImport: parsed.meta.isDefaultImport,
     description: parsed.meta.description,
     category,
     tags: parsed.meta.tags,
@@ -484,6 +485,7 @@ interface GeneratedMetadata {
 interface GenerateOptions {
   componentName: string;
   componentImport: string;
+  isDefaultImport?: boolean;
   description?: string;
   category: string;
   tags?: string[];
@@ -504,6 +506,7 @@ function generateFragmentCode(options: GenerateOptions): string {
   const {
     componentName,
     componentImport,
+    isDefaultImport,
     description,
     category,
     tags,
@@ -550,8 +553,13 @@ ${generated.skippedVariants.map(sv => `      { name: "${escapeString(sv.name)}",
   }
 
   // Import the actual component - this makes the fragment immediately usable
+  // Use default import when the source component uses export default
+  const componentImportStatement = isDefaultImport
+    ? `import ${componentName} from "${componentImport}";`
+    : `import { ${componentName} } from "${componentImport}";`;
+
   return `import { defineFragment } from "@fragments-sdk/cli/core";
-import { ${componentName} } from "${componentImport}";
+${componentImportStatement}
 
 export default defineFragment({
   component: ${componentName},

package/src/migrate/parser.ts

@@ -235,6 +235,7 @@ function parseMeta(
     );
     if (importMatch) {
       result.componentImport = importMatch[1];
+      result.isDefaultImport = false;
     } else {
       // Try default import
       const defaultImportMatch = content.match(
@@ -244,6 +245,7 @@ function parseMeta(
       );
       if (defaultImportMatch) {
         result.componentImport = defaultImportMatch[1];
+        result.isDefaultImport = true;
       }
     }
   }

package/src/migrate/types.ts

@@ -12,6 +12,8 @@ export interface ParsedMeta {
   componentName: string;
   /** Component import path */
   componentImport?: string;
+  /** Whether the component uses a default import (export default) */
+  isDefaultImport?: boolean;
   /** Tags from the story */
   tags?: string[];
   /** Description from parameters.docs */

package/src/service/snippet-validation.test.ts

@@ -2,7 +2,7 @@ import { afterEach, describe, expect, it } from 'vitest';
 import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { tmpdir } from 'node:os';
-import type { FragmentsConfig } from '../core/types.js';
+import type { FragmentsConfig } from '../core/index.js';
 import { validateSnippetPolicy } from './snippet-validation.js';
 
 async function createTempProject(): Promise<string> {

package/src/service/snippet-validation.ts

@@ -2,8 +2,8 @@ import ts from 'typescript';
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import type { FragmentsConfig, SnippetPolicyConfig } from '../core/types.js';
-import { BRAND } from '../core/constants.js';
+import type { FragmentsConfig, SnippetPolicyConfig } from '../core/index.js';
+import { BRAND } from '../core/index.js';
 import {
   discoverBlockFiles,
   discoverFragmentFiles,

package/src/setup.ts

@@ -2,6 +2,7 @@ import pc from 'picocolors';
 import { BRAND } from './core/index.js';
 import { loadConfig, discoverFragmentFiles } from './core/node.js';
 import { buildFragments } from './build.js';
+import { scan } from './commands/scan.js';
 import {
   detectStorybookConfig,
   discoverStoryFiles as discoverStorybookFiles,
@@ -125,48 +126,78 @@ export async function runSetup(options: SetupOptions = {}): Promise<SetupResult>
     let fragmentFiles = await discoverFragmentFiles(config, configDir);
 
     if (fragmentFiles.length === 0 && !options.skipStorybook) {
-      // No fragment files - check for Storybook
+      // No fragment files - check for Storybook stories that the viewer can load directly
       log(pc.yellow('\n   No fragment files found'));
 
       const sbConfig = await detectStorybookConfig(configDir);
       if (sbConfig) {
         log(pc.dim(`   Found Storybook at ${sbConfig.configPath}`));
-        log(pc.dim('   Converting stories to fragments...\n'));
 
-        // Discover and convert stories
-        const storyFiles = await discoverStorybookFiles(configDir, sbConfig.storyPatterns);
+        // Check if config.include already covers story files
+        const hasStoryPatterns = config.include.some((p: string) => p.includes('.stories.'));
 
-        if (storyFiles.length > 0) {
-          let converted = 0;
-          for (const storyFile of storyFiles) {
-            try {
-              const parsed = await parseStoryFile(storyFile);
-              const fragmentResult = convertToFragment(parsed);
+        if (hasStoryPatterns) {
+          // Stories are in the include config — discover them directly
+          // The viewer handles .stories.tsx natively via storyModuleToFragment()
+          log(pc.dim('   Stories included in config — viewer will load them directly\n'));
+          fragmentFiles = await discoverFragmentFiles(config, configDir);
 
-              // Create directory and write file
-              await fs.mkdir(path.dirname(fragmentResult.outputFile), { recursive: true });
-              await fs.writeFile(fragmentResult.outputFile, fragmentResult.code);
-              converted++;
-            } catch {
-              // Skip files that can't be converted
-            }
+          if (fragmentFiles.length > 0) {
+            log(pc.green(`   Found ${fragmentFiles.length} story/fragment file(s)`));
           }
+        } else {
+          // Stories not in config — fall back to conversion
+          log(pc.dim('   Converting stories to fragments...\n'));
+
+          const storyFiles = await discoverStorybookFiles(configDir, sbConfig.storyPatterns);
+
+          if (storyFiles.length > 0) {
+            let converted = 0;
+            for (const storyFile of storyFiles) {
+              try {
+                const parsed = await parseStoryFile(storyFile);
+                const fragmentResult = convertToFragment(parsed);
+
+                // Create directory and write file
+                await fs.mkdir(path.dirname(fragmentResult.outputFile), { recursive: true });
+                await fs.writeFile(fragmentResult.outputFile, fragmentResult.code);
+                converted++;
+              } catch {
+                // Skip files that can't be converted
+              }
+            }
 
-          result.fragmentFilesCreated = converted;
-          log(pc.green(`   Generated ${converted} fragment file(s)`));
+            result.fragmentFilesCreated = converted;
+            log(pc.green(`   Generated ${converted} fragment file(s)`));
 
-          // Refresh fragment files list
-          fragmentFiles = await discoverFragmentFiles(config, configDir);
+            // Refresh fragment files list
+            fragmentFiles = await discoverFragmentFiles(config, configDir);
+          }
         }
       } else {
+        // No Storybook — auto-scan source code to generate fragments.json
         log(pc.dim('   No Storybook config found'));
-        log(pc.dim(`   Run ${pc.cyan(`${BRAND.cliCommand} add <ComponentName>`)} to create your first fragment`));
+        log(pc.dim('   Auto-scanning source code...\n'));
+
+        try {
+          const scanResult = await scan({
+            config: options.configPath,
+            verbose: false,
+          });
+
+          if (scanResult.componentCount > 0) {
+            result.fragmentsBuilt = scanResult.componentCount;
+            log(pc.green(`   Scanned ${scanResult.componentCount} component(s) from source`));
+          }
+        } catch {
+          log(pc.dim(`   Run ${pc.cyan(`${BRAND.cliCommand} scan`)} to generate documentation from source`));
+        }
       }
     } else if (fragmentFiles.length > 0) {
       log(pc.green(`   Found ${fragmentFiles.length} fragment file(s)`));
     }
 
-    // Step 2: Build fragments.json if needed
+    // Step 2: Build fragments.json if needed (only when fragment files exist)
     if (fragmentFiles.length > 0 && !options.skipBuild) {
       const outFile = config.outFile || BRAND.outFile;
       const { stale, missing } = await isFragmentsJsonStale(configDir, outFile);
@@ -185,7 +216,21 @@ export async function runSetup(options: SetupOptions = {}): Promise<SetupResult>
             }
           }
 
-          log(pc.green(`   Built ${buildResult.fragmentCount} fragment(s)`));
+          if (buildResult.fragmentCount > 0) {
+            log(pc.green(`   Built ${buildResult.fragmentCount} fragment(s)`));
+          } else {
+            // Build found 0 fragments — fallback to scan
+            log(pc.dim('   No compilable fragments found, falling back to source scan...'));
+            try {
+              const scanResult = await scan({ verbose: false });
+              if (scanResult.componentCount > 0) {
+                result.fragmentsBuilt = scanResult.componentCount;
+                log(pc.green(`   Scanned ${scanResult.componentCount} component(s) from source`));
+              }
+            } catch {
+              // scan failed silently
+            }
+          }
         } catch (error) {
           result.errors.push(`Build failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
         }

package/src/viewer/__tests__/viewer-integration.test.ts

@@ -68,17 +68,11 @@ describe("@fragments-sdk/cli/core alias resolution", () => {
     expect(existsSync(corePath)).toBe(true);
   });
 
-  it("core/index.ts exports storyModuleToFragment", async () => {
+  it("core/index.ts re-exports from @fragments-sdk/core", async () => {
     const corePath = resolve(cliPackageRoot, "src/core/index.ts");
     const content = await readFile(corePath, "utf-8");
-    // The virtual module imports { storyModuleToFragment, setPreviewConfig }
-    expect(content).toContain("storyModuleToFragment");
-  });
-
-  it("core/index.ts exports setPreviewConfig", async () => {
-    const corePath = resolve(cliPackageRoot, "src/core/index.ts");
-    const content = await readFile(corePath, "utf-8");
-    expect(content).toContain("setPreviewConfig");
+    // After core extraction, cli/core is a thin re-export shim
+    expect(content).toContain("@fragments-sdk/core");
   });
 });
 
@@ -91,7 +85,7 @@ describe("virtual module @fragments-sdk/cli/core import", () => {
 
     // The generated virtual module string should reference @fragments-sdk/cli/core
     expect(content).toContain(
-      'import { storyModuleToFragment, setPreviewConfig } from "@fragments-sdk/cli/core"'
+      'import { storyModuleToFragment, setPreviewConfig, checkStoryExclusion, isForceIncluded, isConfigExcluded } from "@fragments-sdk/cli/core"'
     );
   });