@fragments-sdk/cli 0.14.3 → 0.15.1

package/src/bin.ts

@@ -17,13 +17,14 @@ import { loadConfig } from './core/node.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8')) as { version: string };
 
+const EXPERIMENTAL = process.env.FRAGMENTS_EXPERIMENTAL === '1';
+
 // Import command implementations
 import { validate } from './commands/validate.js';
 import { build } from './commands/build.js';
 import { context } from './commands/context.js';
 import { list } from './commands/list.js';
 import { reset } from './commands/reset.js';
-import { dev } from './commands/dev.js';
 import { compare } from './commands/compare.js';
 import { verify } from './commands/verify.js';
 import { audit } from './commands/audit.js';
@@ -36,11 +37,14 @@ import { linkFigma, linkStorybook } from './commands/link/index.js';
 import { enhance } from './commands/enhance.js';
 import { scan } from './commands/scan.js';
 import { graph } from './commands/graph.js';
+import { inspect } from './commands/inspect.js';
+import { discover } from './commands/discover.js';
 import { perf } from './commands/perf.js';
 import { doctor } from './commands/doctor.js';
 import { setup } from './commands/setup.js';
 import { sync } from './commands/sync.js';
 import { governCheck, governInit, governReport, governConnect } from './commands/govern.js';
+import { migrateContract } from './commands/migrate-contract.js';
 
 // Import existing commands that were already extracted
 import { runScreenshotCommand } from './screenshot.js';
@@ -119,6 +123,8 @@ program
   .option('--registry', `Also generate ${BRAND.dataDir}/${BRAND.registryFile} and ${BRAND.contextFile}`)
   .option('--registry-only', `Only generate ${BRAND.dataDir}/ directory (skip ${BRAND.outFile})`)
   .option('--from-source', 'Build from source code (zero-config, no fragment files needed)')
+  .option('--if-needed', `Skip rebuilding when ${BRAND.outFile} is already fresh`)
+  .option('--check', `Check whether ${BRAND.outFile} is fresh and exit non-zero if it is stale`)
   .option('--skip-usage', 'Skip usage analysis when building from source')
   .option('--skip-storybook', 'Skip Storybook parsing when building from source')
   .option('-v, --verbose', 'Verbose output')
@@ -130,6 +136,8 @@ program
         registry: options.registry,
         registryOnly: options.registryOnly,
         fromSource: options.fromSource,
+        ifNeeded: options.ifNeeded,
+        check: options.check,
         skipUsage: options.skipUsage,
         skipStorybook: options.skipStorybook,
         verbose: options.verbose,
@@ -304,37 +312,6 @@ linkCommand
     }
   });
 
-// ============================================================================
-// DEV COMMAND
-// ============================================================================
-program
-  .command('dev')
-  .description('Start the development server with live component rendering')
-  .option('-p, --port <port>', 'Port to run on', '6006')
-  .option('--no-open', 'Do not open browser')
-  .option('--skip-setup', 'Skip auto-setup (Storybook import, build, Figma link)')
-  .option('--skip-storybook', 'Skip auto-importing from Storybook')
-  .option('--skip-figma', 'Skip Figma link check')
-  .option('--skip-build', `Skip auto-building ${BRAND.outFile}`)
-  .action(async (options) => {
-    try {
-      await dev({
-        port: options.port,
-        open: options.open,
-        skipSetup: options.skipSetup,
-        skipStorybook: options.skipStorybook,
-        skipFigma: options.skipFigma,
-        skipBuild: options.skipBuild,
-      });
-    } catch (error) {
-      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
-      if (error instanceof Error && error.stack) {
-        console.error(pc.dim(error.stack));
-      }
-      process.exit(1);
-    }
-  });
-
 // ============================================================================
 // SCREENSHOT COMMAND
 // ============================================================================
@@ -433,7 +410,7 @@ program
       }
     } catch (error) {
       console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
-      console.log(pc.dim(`\nMake sure the dev server is running: ${BRAND.cliCommand} dev`));
+      console.log(pc.dim(`\nMake sure a dev server is running on the expected port.`));
       process.exit(1);
     }
   });
@@ -642,6 +619,33 @@ program
     }
   });
 
+// ============================================================================
+// MIGRATE-CONTRACT COMMAND
+// ============================================================================
+program
+  .command('migrate-contract')
+  .description('Migrate .fragment.tsx files to .contract.json format')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--glob <pattern>', 'Glob pattern for fragment files', 'src/**/*.fragment.tsx')
+  .option('--dry-run', 'Preview migration without writing files')
+  .option('--tsconfig <path>', 'Path to tsconfig.json')
+  .action(async (options) => {
+    try {
+      const result = await migrateContract({
+        config: options.config,
+        glob: options.glob,
+        dryRun: options.dryRun,
+        tsconfig: options.tsconfig,
+      });
+      if (result.failed > 0) {
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
 // ============================================================================
 // STORYGEN COMMAND
 // ============================================================================
@@ -714,7 +718,7 @@ program
     } catch (error) {
       console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
       if (action === 'update') {
-        console.log(pc.dim(`\nMake sure the dev server is running: ${BRAND.cliCommand} dev`));
+        console.log(pc.dim(`\nMake sure a dev server is running on the expected port.`));
       }
       process.exit(1);
     }
@@ -791,6 +795,47 @@ program
     }
   });
 
+// ============================================================================
+// CREATE COMMAND
+// ============================================================================
+program
+  .command('create')
+  .argument('[name]', 'Project name')
+  .description('Create a new project with Fragments UI and your custom theme')
+  .option('-t, --template <template>', 'Framework template (nextjs, vite)', 'nextjs')
+  .option('--pm <manager>', 'Package manager (npm, pnpm, yarn, bun)')
+  .option('--theme <encoded>', 'Encoded theme string')
+  .option('--preset <id>', 'Theme preset ID from usefragments.com/create')
+  .option('--brand <color>', 'Brand color hex (e.g., #6366f1)')
+  .option('--scss', 'Use SCSS output (installs sass)')
+  .option('--mcp', 'Configure MCP server for AI tooling')
+  .option('-y, --yes', 'Skip interactive prompts')
+  .option('--no-git', 'Skip git initialization')
+  .action(async (name, options) => {
+    try {
+      const { create } = await import('./commands/create.js');
+      const result = await create({
+        name,
+        template: options.template,
+        packageManager: options.pm,
+        theme: options.theme,
+        preset: options.preset,
+        brand: options.brand,
+        scss: options.scss,
+        mcp: options.mcp,
+        yes: options.yes,
+        noGit: !options.git,
+      });
+      if (!result.success) {
+        if (result.error) console.error(pc.red(`Error: ${result.error}`));
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
 // ============================================================================
 // SETUP COMMAND
 // ============================================================================
@@ -823,27 +868,40 @@ program
 // ============================================================================
 // INIT COMMAND
 // ============================================================================
-program
+const initCmd = program
   .command('init')
   .description('Initialize fragments in a project (zero-config by default)')
   .option('--force', 'Overwrite existing config')
   .option('-y, --yes', 'Non-interactive mode (now the default)')
-  .option('--cloud', 'Set up Fragments Cloud governance (zero-config browser auth)')
-  .option('--cloud-url <url>', 'Cloud dashboard URL (default: https://app.usefragments.com)')
-  .option('--port <port>', 'Localhost port for auth callback (default: 9876)')
-  .option('--auth-only', 'Only authenticate, skip project setup')
-  .option('--skip-check', 'Skip running the first governance check')
   .option('--configure', 'Interactive mode for theme seeds, snapshots, etc.')
+  .option('--metadata-only', 'Generate config and metadata without modifying runtime app setup')
+  .option('--govern', 'Alias for --metadata-only')
   .option('--scan <path>', 'Scan a TypeScript component directory and generate fragment files')
   .option('--enrich', 'Use AI to fill knowledge fields during --scan (requires API key)')
   .option('--dry-run', 'Show what --enrich would generate without calling API')
   .option('--provider <provider>', 'AI provider for enrichment: anthropic or openai')
   .option('--api-key <key>', 'API key for AI enrichment')
-  .option('--model <model>', 'Override AI model for enrichment')
-  .action(async (options) => {
+  .option('--model <model>', 'Override AI model for enrichment');
+
+// Cloud governance flags — only visible with FRAGMENTS_EXPERIMENTAL=1
+if (EXPERIMENTAL) {
+  initCmd
+    .option('--cloud', 'Set up Fragments Cloud governance (zero-config browser auth)')
+    .option('--cloud-url <url>', 'Cloud dashboard URL (default: https://app.usefragments.com)')
+    .option('--port <port>', 'Localhost port for auth callback (default: 9876)')
+    .option('--auth-only', 'Only authenticate, skip project setup')
+    .option('--skip-check', 'Skip running the first governance check');
+}
+
+initCmd.action(async (options) => {
     try {
-      // Cloud init — separate flow
+      // Cloud init — experimental, requires FRAGMENTS_EXPERIMENTAL=1
       if (options.cloud) {
+        if (!EXPERIMENTAL) {
+          console.log(pc.yellow(`\n  Fragments Cloud is not yet publicly available.`));
+          console.log(pc.dim(`  Set FRAGMENTS_EXPERIMENTAL=1 to enable preview features.\n`));
+          process.exit(1);
+        }
         const { initCloud } = await import('./commands/init-cloud.js');
         await initCloud({
           url: options.cloudUrl,
@@ -866,6 +924,8 @@ program
         provider: options.provider,
         apiKey: options.apiKey,
         model: options.model,
+        metadataOnly: options.metadataOnly,
+        govern: options.govern,
       });
 
       if (!result.success) {
@@ -912,11 +972,15 @@ program
   });
 
 // ============================================================================
-// TOKENS COMMAND
+// TOKENS COMMAND GROUP
 // ============================================================================
-program
+const tokensCmd = program
   .command('tokens')
-  .description('Discover and list design tokens from CSS/SCSS files')
+  .description('Design token discovery, listing, and generation');
+
+tokensCmd
+  .command('list', { isDefault: true })
+  .description('Discover and list design tokens from CSS/SCSS/DTCG files')
   .option('-c, --config <path>', 'Path to config file')
   .option('--json', 'Output as JSON')
   .option('--categories', 'Group tokens by category')
@@ -944,6 +1008,54 @@ program
     }
   });
 
+tokensCmd
+  .command('generate')
+  .description('Generate CSS, SCSS, Tailwind, or Figma output from a DTCG .tokens.json file')
+  .requiredOption('--from <path>', 'Path to DTCG .tokens.json source file')
+  .requiredOption('--format <formats>', 'Output formats (comma-separated: css, scss, tailwind, figma)')
+  .option('--out <dir>', 'Output directory (default: same directory as source)')
+  .option('--prefix <prefix>', 'Token name prefix')
+  .option('--selector <selector>', 'CSS selector for custom properties (default: :root)')
+  .option('--verbose', 'Verbose output')
+  .action(async (options) => {
+    try {
+      const { tokensGenerate } = await import('./commands/tokens-generate.js');
+      await tokensGenerate({
+        from: options.from,
+        format: options.format,
+        out: options.out,
+        prefix: options.prefix,
+        selector: options.selector,
+        verbose: options.verbose,
+      });
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+tokensCmd
+  .command('push')
+  .description('Push code tokens to Fragments Cloud for drift comparison')
+  .option('-c, --config <path>', 'Path to fragments config file')
+  .option('--tailwind-v4 <path>', 'Path to Tailwind v4 CSS file with @theme block')
+  .option('--dry-run', 'Parse and display tokens without pushing')
+  .option('--verbose', 'Show detailed output')
+  .action(async (options) => {
+    try {
+      const { tokensPush } = await import('./commands/tokens-push.js');
+      await tokensPush({
+        config: options.config,
+        tailwindV4: options.tailwindV4,
+        dryRun: options.dryRun,
+        verbose: options.verbose,
+      });
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
 // ============================================================================
 // GENERATE COMMAND
 // ============================================================================
@@ -995,6 +1107,71 @@ program
     }
   });
 
+// ============================================================================
+// INSPECT COMMAND
+// ============================================================================
+program
+  .command('inspect')
+  .description('Inspect a single component from compiled fragments data')
+  .argument('<component>', 'Component name to inspect')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--fields <fields>', 'Comma-separated fields to include (dot notation: meta, props, examples)')
+  .option('--variant <name>', 'Filter to a specific variant')
+  .option('--verbosity <level>', 'Output verbosity: compact, standard, full', 'standard')
+  .option('--maxExamples <n>', 'Max variant examples to include', (v) => Number.parseInt(v, 10))
+  .option('--json', 'Output as JSON')
+  .action(async (component, options) => {
+    try {
+      await inspect(component, {
+        config: options.config,
+        fields: options.fields,
+        variant: options.variant,
+        verbosity: options.verbosity,
+        maxExamples: options.maxExamples,
+        json: options.json,
+      });
+    } catch (error) {
+      if (options.json) {
+        console.log(JSON.stringify({ error: error instanceof Error ? error.message : 'Inspect failed' }));
+      } else {
+        console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      }
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// DISCOVER COMMAND
+// ============================================================================
+program
+  .command('discover')
+  .description('List and filter components from compiled fragments data')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--search <term>', 'Search by name, description, or tags')
+  .option('--category <category>', 'Filter by category')
+  .option('--status <status>', 'Filter by status: stable, beta, deprecated, experimental')
+  .option('--compact', 'Output component names only')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    try {
+      await discover({
+        config: options.config,
+        search: options.search,
+        category: options.category,
+        status: options.status,
+        compact: options.compact,
+        json: options.json,
+      });
+    } catch (error) {
+      if (options.json) {
+        console.log(JSON.stringify({ error: error instanceof Error ? error.message : 'Discover failed' }));
+      } else {
+        console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      }
+      process.exit(1);
+    }
+  });
+
 // ============================================================================
 // PERF COMMAND
 // ============================================================================
@@ -1134,11 +1311,18 @@ program
   });
 
 // ============================================================================
-// GOVERN COMMAND
+// GOVERN COMMAND (experimental — FRAGMENTS_EXPERIMENTAL=1)
 // ============================================================================
 const governCmd = program
   .command('govern')
-  .description('AI UI governance checks');
+  .description(EXPERIMENTAL ? 'AI UI governance checks' : 'AI UI governance checks (preview — set FRAGMENTS_EXPERIMENTAL=1)')
+  .hook('preAction', () => {
+    if (!EXPERIMENTAL) {
+      console.log(pc.yellow(`\n  Fragments governance is not yet publicly available.`));
+      console.log(pc.dim(`  Set FRAGMENTS_EXPERIMENTAL=1 to enable preview features.\n`));
+      process.exit(1);
+    }
+  });
 
 governCmd
   .command('check')
@@ -1199,5 +1383,73 @@ governCmd
     }
   });
 
+governCmd
+  .command('scan')
+  .description('Scan JSX/TSX codebase for governance violations')
+  .option('-d, --dir <path>', 'Root directory (default: auto-detect)')
+  .option('-c, --config <path>', 'Path to govern.config.ts')
+  .option('-f, --format <format>', 'Output format: summary, json, sarif', 'summary')
+  .option('-q, --quiet', 'Suppress non-error output')
+  .action(async (options) => {
+    try {
+      const { governScan } = await import('./commands/govern-scan.js');
+      const { exitCode } = await governScan({
+        dir: options.dir,
+        config: options.config,
+        format: options.format,
+        quiet: options.quiet,
+      });
+      process.exit(exitCode);
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+governCmd
+  .command('watch')
+  .description('Watch JSX/TSX files and re-check on changes')
+  .option('-d, --dir <path>', 'Root directory (default: auto-detect)')
+  .option('-c, --config <path>', 'Path to govern.config.ts')
+  .option('-q, --quiet', 'Suppress non-error output')
+  .option('--debounce <ms>', 'Debounce interval in ms', '300')
+  .action(async (options) => {
+    try {
+      const { governWatch } = await import('./commands/govern-scan.js');
+      await governWatch({
+        dir: options.dir,
+        config: options.config,
+        quiet: options.quiet,
+        debounce: parseInt(options.debounce, 10),
+      });
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+governCmd
+  .command('push-contracts')
+  .description('Push component contracts to Fragments Cloud')
+  .option('-i, --input <path>', 'Path to fragments.json (default: ./fragments.json)')
+  .option('--url <url>', 'Fragments Cloud URL')
+  .option('--api-key <key>', 'API key (default: FRAGMENTS_API_KEY env var)')
+  .option('-q, --quiet', 'Suppress non-error output')
+  .action(async (options) => {
+    try {
+      const { pushContracts } = await import('./commands/push-contracts.js');
+      const { exitCode } = await pushContracts({
+        input: options.input,
+        url: options.url,
+        apiKey: options.apiKey,
+        quiet: options.quiet,
+      });
+      process.exit(exitCode);
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
 // Parse command line arguments
 program.parse();

package/src/commands/__fixtures__/shadcn-label-wrapper/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "shadcn-label-wrapper",
+  "private": true,
+  "devDependencies": {
+    "@fragments-sdk/core": "^1.0.1"
+  }
+}

package/src/commands/__fixtures__/shadcn-label-wrapper/src/components/ui/label.contract.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Label",
+  "description": "Label component",
+  "category": "Typography",
+  "sourcePath": "label.tsx",
+  "exportName": "Label",
+  "propsSummary": [
+    "className: string",
+    "htmlFor: string",
+    "form: string",
+    "children: node"
+  ],
+  "props": {
+    "className": {
+      "type": "string",
+      "description": ""
+    },
+    "htmlFor": {
+      "type": "string",
+      "description": ""
+    },
+    "form": {
+      "type": "string",
+      "description": ""
+    },
+    "children": {
+      "type": "node",
+      "description": ""
+    }
+  },
+  "usage": {
+    "when": [],
+    "whenNot": []
+  },
+  "provenance": {
+    "source": "extracted",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-22T23:45:29.606Z"
+  }
+}

package/src/commands/__fixtures__/shadcn-label-wrapper/src/components/ui/label.tsx

@@ -0,0 +1,11 @@
+import * as React from "react";
+import { Primitive } from "./primitive";
+
+function Label({
+  className,
+  ...props
+}: React.ComponentProps<typeof Primitive.Root>) {
+  return <Primitive.Root data-class={className} {...props} />;
+}
+
+export { Label };

package/src/commands/__fixtures__/shadcn-label-wrapper/src/components/ui/primitive.contract.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Primitive",
+  "description": "Primitive component",
+  "category": "Components",
+  "sourcePath": "primitive.tsx",
+  "exportName": "Primitive",
+  "propsSummary": [],
+  "props": {},
+  "usage": {
+    "when": [],
+    "whenNot": []
+  },
+  "provenance": {
+    "source": "extracted",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-22T23:45:29.607Z"
+  }
+}

package/src/commands/__fixtures__/shadcn-label-wrapper/src/components/ui/primitive.tsx

@@ -0,0 +1,14 @@
+import * as React from "react";
+
+export interface PrimitiveLabelProps {
+  className?: string;
+  htmlFor?: string;
+  form?: string;
+  children?: React.ReactNode;
+}
+
+function Root(props: PrimitiveLabelProps) {
+  return <label {...props} />;
+}
+
+export const Primitive = { Root };

package/src/commands/__fixtures__/shadcn-label-wrapper/tsconfig.app.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": [
+      "react",
+      "react-dom"
+    ]
+  },
+  "include": [
+    "src/**/*.tsx"
+  ],
+  "exclude": [
+    "**/*.fragment.tsx",
+    "**/*.contract.json"
+  ]
+}