@fragments-sdk/cli 0.15.0 → 0.15.1

package/src/bin.ts

@@ -123,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')
@@ -134,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,
@@ -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
 // ============================================================================
@@ -989,6 +1034,28 @@ tokensCmd
     }
   });
 
+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
 // ============================================================================
@@ -1361,5 +1428,28 @@ governCmd
     }
   });
 
+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/src/components/ui/label.contract.json

@@ -37,6 +37,6 @@
     "source": "extracted",
     "verified": false,
     "frameworkSupport": "native",
-    "extractedAt": "2026-03-13T23:33:02.488Z"
+    "extractedAt": "2026-03-22T23:45:29.606Z"
   }
 }

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

@@ -15,6 +15,6 @@
     "source": "extracted",
     "verified": false,
     "frameworkSupport": "native",
-    "extractedAt": "2026-03-13T23:33:02.489Z"
+    "extractedAt": "2026-03-22T23:45:29.607Z"
   }
 }

package/src/commands/__tests__/build-freshness.test.ts

@@ -0,0 +1,231 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { mkdtemp, mkdir, rm, utimes, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { getFragmentsBuildInputs, getFragmentsJsonStatus, getGeneratorVersion } from '@fragments-sdk/compiler';
+import type { FragmentsConfig } from '@fragments-sdk/core';
+
+describe('getFragmentsJsonStatus', () => {
+  let tmpDir: string;
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'build-freshness-test-'));
+  });
+
+  afterAll(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  async function createProject(projectName: string) {
+    const projectDir = join(tmpDir, projectName);
+    const srcDir = join(projectDir, 'src', 'components');
+    await mkdir(srcDir, { recursive: true });
+
+    const configPath = join(projectDir, 'fragments.config.ts');
+    const fragmentPath = join(srcDir, 'Button.contract.json');
+    const componentPath = join(srcDir, 'Button.tsx');
+    const outputPath = join(projectDir, 'fragments.json');
+
+    await writeFile(
+      configPath,
+      `export default {
+  include: ['src/**/*.contract.json'],
+  exclude: [],
+  components: ['src/**/*.tsx'],
+  framework: 'react',
+  outFile: 'fragments.json',
+};
+`
+    );
+
+    await writeFile(
+      fragmentPath,
+      JSON.stringify(
+        {
+          name: 'Button',
+          description: 'Button component',
+          category: 'actions',
+          variants: [
+            {
+              name: 'Default',
+              code: '<Button>Press</Button>',
+            },
+          ],
+          sourcePath: 'src/components/Button.tsx',
+          exportName: 'Button',
+        },
+        null,
+        2
+      )
+    );
+
+    await writeFile(
+      componentPath,
+      `export function Button() {
+  return null;
+}
+`
+    );
+
+    const config: FragmentsConfig = {
+      include: ['src/**/*.contract.json'],
+      exclude: [],
+      components: ['src/**/*.tsx'],
+      framework: 'react',
+      outFile: 'fragments.json',
+    };
+
+    return {
+      config,
+      projectDir,
+      configPath,
+      fragmentPath,
+      componentPath,
+      outputPath,
+    };
+  }
+
+  it('reports missing output files', async () => {
+    const project = await createProject('missing-output');
+
+    const status = await getFragmentsJsonStatus(project.config, project.projectDir, {
+      configPath: project.configPath,
+    });
+
+    expect(status.missing).toBe(true);
+    expect(status.stale).toBe(false);
+    expect(status.reason).toBe('missing output file');
+  });
+
+  it('accepts a fresh fragments.json with matching inputs and generator version', async () => {
+    const project = await createProject('fresh-output');
+    const generatorVersion = await getGeneratorVersion();
+    const buildInputs = await getFragmentsBuildInputs(project.config, project.projectDir, {
+      configPath: project.configPath,
+    });
+
+    await writeFile(
+      project.outputPath,
+      JSON.stringify(
+        {
+          version: '1.0.0',
+          generatedAt: new Date().toISOString(),
+          generatorVersion,
+          buildInputs: buildInputs.relativePaths,
+          fragments: {},
+        },
+        null,
+        2
+      )
+    );
+
+    const now = new Date();
+    const earlier = new Date(now.getTime() - 10_000);
+    await utimes(project.configPath, earlier, earlier);
+    await utimes(project.fragmentPath, earlier, earlier);
+    await utimes(project.componentPath, earlier, earlier);
+    await utimes(project.outputPath, now, now);
+
+    const status = await getFragmentsJsonStatus(project.config, project.projectDir, {
+      configPath: project.configPath,
+    });
+
+    expect(status.missing).toBe(false);
+    expect(status.stale).toBe(false);
+    expect(status.reason).toBeNull();
+  });
+
+  it('marks fragments.json stale when a new input file is added', async () => {
+    const project = await createProject('added-input');
+    const generatorVersion = await getGeneratorVersion();
+    const buildInputs = await getFragmentsBuildInputs(project.config, project.projectDir, {
+      configPath: project.configPath,
+    });
+
+    // Write fragments.json with current inputs
+    await writeFile(
+      project.outputPath,
+      JSON.stringify(
+        {
+          version: '1.0.0',
+          generatedAt: new Date().toISOString(),
+          generatorVersion,
+          buildInputs: buildInputs.relativePaths,
+          fragments: {},
+        },
+        null,
+        2
+      )
+    );
+
+    // Add a new component file — buildInputs list will differ
+    const newComponentPath = join(project.projectDir, 'src', 'components', 'Input.tsx');
+    await writeFile(newComponentPath, 'export function Input() { return null; }\n');
+
+    const status = await getFragmentsJsonStatus(project.config, project.projectDir, {
+      configPath: project.configPath,
+    });
+
+    expect(status.stale).toBe(true);
+    expect(status.reason).toContain('build inputs changed');
+  });
+
+  it('marks legacy fragments.json without build metadata as stale', async () => {
+    const project = await createProject('legacy-output');
+    const generatorVersion = await getGeneratorVersion();
+
+    await writeFile(
+      project.outputPath,
+      JSON.stringify(
+        {
+          version: '1.0.0',
+          generatedAt: new Date().toISOString(),
+          generatorVersion,
+          fragments: {},
+        },
+        null,
+        2
+      )
+    );
+
+    const status = await getFragmentsJsonStatus(project.config, project.projectDir, {
+      configPath: project.configPath,
+    });
+
+    expect(status.stale).toBe(true);
+    expect(status.reason).toBe('missing build input metadata');
+  });
+
+  it('marks fragments.json stale when an input file disappears', async () => {
+    const project = await createProject('deleted-input');
+    const generatorVersion = await getGeneratorVersion();
+    const buildInputs = await getFragmentsBuildInputs(project.config, project.projectDir, {
+      configPath: project.configPath,
+    });
+
+    await writeFile(
+      project.outputPath,
+      JSON.stringify(
+        {
+          version: '1.0.0',
+          generatedAt: new Date().toISOString(),
+          generatorVersion,
+          buildInputs: buildInputs.relativePaths,
+          fragments: {},
+        },
+        null,
+        2
+      )
+    );
+
+    await rm(project.componentPath);
+
+    const status = await getFragmentsJsonStatus(project.config, project.projectDir, {
+      configPath: project.configPath,
+    });
+
+    expect(status.stale).toBe(true);
+    expect(status.reason).toContain('build inputs changed');
+  });
+});

package/src/commands/__tests__/create.test.ts

@@ -0,0 +1,71 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  addNextTranspilePackages,
+  generateNextjsLayout,
+  generateNextjsPage,
+  generateNextjsProviders,
+} from "../create.js";
+
+describe("create command templates", () => {
+  let tmpDir: string;
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "fragments-create-test-"));
+  });
+
+  afterAll(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("generates a Next.js layout that routes providers through a client wrapper", () => {
+    const layout = generateNextjsLayout("../styles/theme.css");
+
+    expect(layout).toContain("import { Providers } from './providers';");
+    expect(layout).toContain("<Providers>{children}</Providers>");
+    expect(layout).not.toContain("ThemeProvider");
+  });
+
+  it("generates a client providers module for Next.js", () => {
+    const providers = generateNextjsProviders();
+
+    expect(providers).toContain("'use client';");
+    expect(providers).toContain("ThemeProvider");
+    expect(providers).toContain("ToastProvider");
+  });
+
+  it("marks the sample Next.js page as a client component", () => {
+    const page = generateNextjsPage();
+
+    expect(page).toContain("'use client';");
+    expect(page).toContain("import { Button, Card, Stack, Text, Input } from '@fragments-sdk/ui';");
+  });
+
+  it("adds transpilePackages for @fragments-sdk/ui to next.config.ts", async () => {
+    const projectDir = join(tmpDir, "next-app");
+    await mkdir(projectDir, { recursive: true });
+    const configPath = join(projectDir, "next.config.ts");
+
+    await writeFile(
+      configPath,
+      [
+        'import type { NextConfig } from "next";',
+        "",
+        "const nextConfig: NextConfig = {",
+        "  /* config options here */",
+        "};",
+        "",
+        "export default nextConfig;",
+        "",
+      ].join("\n"),
+    );
+
+    addNextTranspilePackages(projectDir);
+
+    const updated = await readFile(configPath, "utf-8");
+    expect(updated).toContain("transpilePackages: ['@fragments-sdk/ui']");
+  });
+});

package/src/commands/__tests__/drift-sync.test.ts

@@ -3,7 +3,7 @@ import { mkdtemp, writeFile, mkdir, rm, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { diffProps, validateDrift, type DriftItem } from '../../validators.js';
-import type { PropMeta } from '../../core/component-extractor.js';
+import type { PropMeta } from '@fragments-sdk/extract';
 import type { FragmentsConfig } from '@fragments-sdk/core';
 
 // ---------------------------------------------------------------------------