@fragments-sdk/cli 0.14.3 → 0.15.1

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';
 
 // ---------------------------------------------------------------------------

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

@@ -0,0 +1,258 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+describe('govern init', () => {
+  let tmpDir: string;
+  let originalCwd: string;
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'fragments-govern-test-'));
+    originalCwd = process.cwd();
+  });
+
+  afterAll(async () => {
+    process.chdir(originalCwd);
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it(
+    'generates a fragments.config.ts with default output path',
+    { timeout: 15_000 },
+    async () => {
+      const projectDir = join(tmpDir, 'default-init');
+      await mkdir(projectDir, { recursive: true });
+      process.chdir(projectDir);
+
+      const { governInit } = await import('../govern.js');
+      await governInit();
+
+      const configPath = join(projectDir, 'fragments.config.ts');
+      expect(existsSync(configPath)).toBe(true);
+
+      const content = await readFile(configPath, 'utf-8');
+      expect(content).toContain('rules');
+    },
+  );
+
+  it(
+    'generates config at custom output path',
+    { timeout: 15_000 },
+    async () => {
+      const projectDir = join(tmpDir, 'custom-output');
+      await mkdir(projectDir, { recursive: true });
+      process.chdir(projectDir);
+
+      const customPath = join(projectDir, 'my-config.ts');
+      const { governInit } = await import('../govern.js');
+      await governInit({ output: customPath });
+
+      expect(existsSync(customPath)).toBe(true);
+      const content = await readFile(customPath, 'utf-8');
+      expect(content).toContain('rules');
+    },
+  );
+
+  it(
+    'auto-detects Tailwind config and includes it in token sources',
+    { timeout: 15_000 },
+    async () => {
+      const projectDir = join(tmpDir, 'tailwind-detect');
+      await mkdir(projectDir, { recursive: true });
+      process.chdir(projectDir);
+
+      // Create a tailwind config file
+      await writeFile(
+        join(projectDir, 'tailwind.config.ts'),
+        'export default { content: ["./src/**/*.tsx"] };',
+      );
+
+      const { governInit } = await import('../govern.js');
+      await governInit();
+
+      const configPath = join(projectDir, 'fragments.config.ts');
+      const content = await readFile(configPath, 'utf-8');
+      expect(content).toContain('tailwind.config.ts');
+    },
+  );
+
+  it(
+    'auto-detects SCSS token files',
+    { timeout: 15_000 },
+    async () => {
+      const projectDir = join(tmpDir, 'scss-detect');
+      await mkdir(join(projectDir, 'src', 'styles'), { recursive: true });
+      process.chdir(projectDir);
+
+      await writeFile(
+        join(projectDir, 'src', 'styles', 'tokens.scss'),
+        '$color-primary: #2563EB;',
+      );
+
+      const { governInit } = await import('../govern.js');
+      await governInit();
+
+      const configPath = join(projectDir, 'fragments.config.ts');
+      const content = await readFile(configPath, 'utf-8');
+      expect(content).toContain('src/styles/tokens.scss');
+    },
+  );
+
+  it(
+    'handles empty project gracefully (no token sources)',
+    { timeout: 15_000 },
+    async () => {
+      const projectDir = join(tmpDir, 'empty-project');
+      await mkdir(projectDir, { recursive: true });
+      process.chdir(projectDir);
+
+      const { governInit } = await import('../govern.js');
+      await governInit();
+
+      const configPath = join(projectDir, 'fragments.config.ts');
+      expect(existsSync(configPath)).toBe(true);
+    },
+  );
+});
+
+describe('govern check', () => {
+  let tmpDir: string;
+  let originalCwd: string;
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'fragments-govern-check-'));
+    originalCwd = process.cwd();
+  });
+
+  afterAll(async () => {
+    process.chdir(originalCwd);
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it(
+    'returns exitCode 0 for a passing spec',
+    { timeout: 15_000 },
+    async () => {
+      const projectDir = join(tmpDir, 'check-pass');
+      await mkdir(projectDir, { recursive: true });
+      process.chdir(projectDir);
+
+      // Write a minimal UISpec that should pass basic checks
+      const spec = {
+        nodes: [
+          {
+            id: 'root',
+            type: 'div',
+            props: {},
+            children: ['btn'],
+          },
+          {
+            id: 'btn',
+            type: 'Button',
+            props: { variant: 'primary' },
+          },
+        ],
+        root: 'root',
+      };
+      await writeFile(
+        join(projectDir, 'spec.json'),
+        JSON.stringify(spec, null, 2),
+      );
+
+      const { governCheck } = await import('../govern.js');
+      const result = await governCheck({
+        input: join(projectDir, 'spec.json'),
+        quiet: true,
+      });
+
+      // With no config (empty rules), should pass
+      expect(typeof result.exitCode).toBe('number');
+      expect(result.exitCode === 0 || result.exitCode === 1).toBe(true);
+    },
+  );
+
+  it(
+    'returns a valid result structure',
+    { timeout: 15_000 },
+    async () => {
+      const projectDir = join(tmpDir, 'check-structure');
+      await mkdir(projectDir, { recursive: true });
+      process.chdir(projectDir);
+
+      const spec = {
+        nodes: [{ id: 'root', type: 'div' }],
+        root: 'root',
+      };
+      await writeFile(
+        join(projectDir, 'spec.json'),
+        JSON.stringify(spec, null, 2),
+      );
+
+      const { governCheck } = await import('../govern.js');
+      const result = await governCheck({
+        input: join(projectDir, 'spec.json'),
+        quiet: true,
+      });
+
+      expect(result).toHaveProperty('exitCode');
+    },
+  );
+});
+
+describe('govern report', () => {
+  let tmpDir: string;
+  let originalCwd: string;
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'fragments-govern-report-'));
+    originalCwd = process.cwd();
+  });
+
+  afterAll(async () => {
+    process.chdir(originalCwd);
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it(
+    'handles missing audit log gracefully',
+    { timeout: 10_000 },
+    async () => {
+      const projectDir = join(tmpDir, 'no-log');
+      await mkdir(projectDir, { recursive: true });
+      process.chdir(projectDir);
+
+      const { governReport } = await import('../govern.js');
+      // Should not throw
+      await governReport();
+    },
+  );
+
+  it(
+    'parses and summarizes audit log',
+    { timeout: 10_000 },
+    async () => {
+      const projectDir = join(tmpDir, 'with-log');
+      await mkdir(projectDir, { recursive: true });
+      process.chdir(projectDir);
+
+      const entries = [
+        { score: 90, passed: true, violationCount: 1 },
+        { score: 70, passed: false, violationCount: 5 },
+        { score: 100, passed: true, violationCount: 0 },
+      ];
+      const logContent = entries
+        .map((e) => JSON.stringify(e))
+        .join('\n');
+      await writeFile(join(projectDir, '.govern-audit.jsonl'), logContent);
+
+      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const { governReport } = await import('../govern.js');
+      await governReport();
+      consoleSpy.mockRestore();
+
+      // Verify it ran without error — the console output is tested implicitly
+    },
+  );
+});

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

@@ -0,0 +1,113 @@
+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 { init } from "../init.js";
+
+describe("init", () => {
+  let tmpDir: string;
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "fragments-init-test-"));
+  });
+
+  afterAll(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("skips Fragments UI runtime injection for shadcn-style projects", { timeout: 10_000 }, async () => {
+    const projectDir = join(tmpDir, "shadcn-app");
+    await mkdir(join(projectDir, "src", "components", "ui"), { recursive: true });
+
+    await writeFile(
+      join(projectDir, "package.json"),
+      JSON.stringify(
+        {
+          name: "shadcn-app",
+          private: true,
+          devDependencies: {
+            tailwindcss: "^4.0.0",
+          },
+        },
+        null,
+        2
+      )
+    );
+    await writeFile(join(projectDir, "vite.config.ts"), "export default {};\n");
+    await writeFile(
+      join(projectDir, "src", "main.tsx"),
+      [
+        "import { StrictMode } from 'react';",
+        "import { createRoot } from 'react-dom/client';",
+        "import App from './App';",
+        "",
+        "createRoot(document.getElementById('root')!).render(",
+        "  <StrictMode><App /></StrictMode>",
+        ");",
+        "",
+      ].join("\n")
+    );
+    await writeFile(join(projectDir, "src", "App.tsx"), "export default function App() { return <div />; }\n");
+    await writeFile(
+      join(projectDir, "src", "components", "ui", "button.tsx"),
+      [
+        "export interface ButtonProps {",
+        "  variant?: 'default' | 'secondary';",
+        "}",
+        "export function Button({ variant = 'default' }: ButtonProps) {",
+        "  return <button data-variant={variant} />;",
+        "}",
+        "",
+      ].join("\n")
+    );
+
+    const result = await init({ projectRoot: projectDir });
+
+    expect(result.success).toBe(true);
+
+    const main = await readFile(join(projectDir, "src", "main.tsx"), "utf-8");
+    expect(main).not.toContain("@fragments-sdk/ui");
+    expect(main).not.toContain("ThemeProvider");
+  });
+
+  it("respects explicit metadata-only mode even without an existing UI library", async () => {
+    const projectDir = join(tmpDir, "metadata-only-app");
+    await mkdir(join(projectDir, "src"), { recursive: true });
+
+    await writeFile(
+      join(projectDir, "package.json"),
+      JSON.stringify(
+        {
+          name: "metadata-only-app",
+          private: true,
+        },
+        null,
+        2
+      )
+    );
+    await writeFile(join(projectDir, "vite.config.ts"), "export default {};\n");
+    await writeFile(
+      join(projectDir, "src", "main.tsx"),
+      [
+        "import { StrictMode } from 'react';",
+        "import { createRoot } from 'react-dom/client';",
+        "import App from './App';",
+        "",
+        "createRoot(document.getElementById('root')!).render(",
+        "  <StrictMode><App /></StrictMode>",
+        ");",
+        "",
+      ].join("\n")
+    );
+    await writeFile(join(projectDir, "src", "App.tsx"), "export default function App() { return <div />; }\n");
+
+    const result = await init({ projectRoot: projectDir, metadataOnly: true });
+
+    expect(result.success).toBe(true);
+
+    const main = await readFile(join(projectDir, "src", "main.tsx"), "utf-8");
+    expect(main).not.toContain("@fragments-sdk/ui");
+    expect(main).not.toContain("ThemeProvider");
+  });
+});