@fragments-sdk/cli 0.15.10 → 0.16.0

package/src/commands/__tests__/context-cloud.test.ts

@@ -0,0 +1,291 @@
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+import { mkdtemp, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { strToU8, zipSync } from 'fflate';
+
+const confirmMock = vi.hoisted(() => vi.fn());
+
+vi.mock('@inquirer/prompts', () => ({
+  confirm: confirmMock,
+}));
+
+function makeManifest(
+  overrides: Partial<Record<string, unknown>> = {},
+) {
+  return {
+    schemaVersion: 1,
+    catalogRevision: 'abc123',
+    catalogUpdatedAt: '2026-04-01T12:00:00.000Z',
+    org: {
+      id: 'org_123',
+      name: 'Acme',
+      slug: 'acme',
+    },
+    designSystem: {
+      name: 'Acme UI',
+      packageName: '@acme/react',
+      importPath: '@acme/react',
+    },
+    sourceBinding: {
+      bindingId: 'binding_123',
+      projectId: 'project_123',
+      projectName: 'Acme UI',
+      repoFullName: 'acme/ui',
+      resolution: 'explicit',
+    },
+    totalComponents: 2,
+    totalTokens: 1,
+    tokenCategories: {
+      color: 1,
+    },
+    components: {
+      component_1: {
+        componentId: 'component_1',
+        file: '.fragments/components/button-a7f3e2b1.json',
+        name: 'Button',
+        publicSlug: 'button',
+        tier: 'core',
+        category: 'inputs',
+        status: 'stable',
+        description: 'Primary action trigger.',
+        propCount: 2,
+        hasExamples: true,
+        hasCompoundChildren: false,
+        relations: [],
+        compoundChildren: [],
+      },
+    },
+    ...overrides,
+  };
+}
+
+function makeBundleZip(manifestOverrides: Partial<Record<string, unknown>> = {}) {
+  const manifest = makeManifest(manifestOverrides);
+  const files = {
+    '.fragments/manifest.json': JSON.stringify(manifest, null, 2),
+    '.fragments/tokens.json': JSON.stringify(
+      {
+        schemaVersion: 1,
+        catalogRevision: manifest.catalogRevision,
+        catalogUpdatedAt: manifest.catalogUpdatedAt,
+        categories: { color: { count: 1, tokens: [] } },
+        flat: [],
+      },
+      null,
+      2,
+    ),
+    '.fragments/design-system.md': '# Design System: Acme UI',
+    '.fragments/README.md': '# Acme UI Fragments Bundle',
+    '.fragments/instructions/agents.md': 'Agents helper',
+    '.fragments/instructions/claude-code.md': 'Claude helper',
+    '.fragments/instructions/copilot.md': 'Copilot helper',
+    '.cursor/rules/fragments-design-system.mdc': 'Cursor helper',
+  };
+
+  return zipSync(
+    Object.fromEntries(
+      Object.entries(files).map(([path, content]) => [path, strToU8(content)]),
+    ),
+  );
+}
+
+describe('context-cloud commands', () => {
+  let cwd: string;
+  let consoleLogSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(async () => {
+    cwd = await mkdtemp(join(tmpdir(), 'fragments-context-cloud-'));
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    confirmMock.mockReset();
+    vi.stubGlobal('fetch', vi.fn(async (input: string | URL) => {
+      const url = new URL(String(input));
+      if (url.pathname === '/api/bundle') {
+        return new Response(makeBundleZip(), {
+          status: 200,
+          headers: { 'Content-Type': 'application/zip' },
+        });
+      }
+      if (url.pathname === '/api/bundle-artifact') {
+        return Response.json({
+          content: JSON.stringify(makeManifest(), null, 2),
+        });
+      }
+      return Response.json({ error: 'not found' }, { status: 404 });
+    }));
+  });
+
+  afterEach(() => {
+    consoleLogSpy.mockRestore();
+    vi.unstubAllGlobals();
+    delete process.env.FRAGMENTS_API_KEY;
+  });
+
+  it('fails fast when no API key is provided', async () => {
+    const { contextInstallCloud } = await import('../context-cloud');
+
+    await expect(
+      contextInstallCloud({ cwd, rootFiles: 'never' }),
+    ).rejects.toThrow(
+      'Missing Fragments Cloud API key. Set FRAGMENTS_API_KEY or pass --api-key.',
+    );
+  });
+
+  it('installs the downloaded bundle into an empty repo', async () => {
+    const { contextInstallCloud } = await import('../context-cloud');
+
+    await contextInstallCloud({
+      cwd,
+      apiKey: 'fc_test_key',
+      rootFiles: 'never',
+    });
+
+    await expect(
+      readFile(join(cwd, '.fragments/manifest.json'), 'utf-8'),
+    ).resolves.toContain('"schemaVersion": 1');
+    await expect(
+      readFile(
+        join(cwd, '.fragments/instructions/agents.md'),
+        'utf-8',
+      ),
+    ).resolves.toContain('Agents helper');
+    await expect(
+      readFile(
+        join(cwd, '.cursor/rules/fragments-design-system.mdc'),
+        'utf-8',
+      ),
+    ).resolves.toContain('Cursor helper');
+  });
+
+  it('patches root files in prompt mode after confirmation', async () => {
+    const { contextInstallCloud } = await import('../context-cloud');
+    confirmMock.mockResolvedValue(true);
+    await writeFile(join(cwd, 'AGENTS.md'), 'Existing guidance', 'utf-8');
+
+    await contextInstallCloud({
+      cwd,
+      apiKey: 'fc_test_key',
+      rootFiles: 'prompt',
+    });
+
+    await expect(readFile(join(cwd, 'AGENTS.md'), 'utf-8')).resolves.toContain(
+      'BEGIN FRAGMENTS DESIGN SYSTEM',
+    );
+  });
+
+  it('does not patch root files in non-interactive mode without explicit patch', async () => {
+    const { contextInstallCloud } = await import('../context-cloud');
+    await writeFile(join(cwd, 'AGENTS.md'), 'Existing guidance', 'utf-8');
+
+    await contextInstallCloud({
+      cwd,
+      apiKey: 'fc_test_key',
+      yes: true,
+    });
+
+    await expect(readFile(join(cwd, 'AGENTS.md'), 'utf-8')).resolves.toBe(
+      'Existing guidance',
+    );
+  });
+
+  it('can opt .fragments out of git by updating .gitignore', async () => {
+    const { contextInstallCloud } = await import('../context-cloud');
+    await writeFile(join(cwd, '.gitignore'), 'node_modules/\n', 'utf-8');
+
+    await contextInstallCloud({
+      cwd,
+      apiKey: 'fc_test_key',
+      rootFiles: 'never',
+      gitignoreFragments: true,
+    });
+
+    await expect(readFile(join(cwd, '.gitignore'), 'utf-8')).resolves.toContain(
+      '.fragments/',
+    );
+  });
+
+  it('surfaces a readable error when the bundle download is corrupted', async () => {
+    const { contextInstallCloud } = await import('../context-cloud');
+    vi.stubGlobal('fetch', vi.fn(async (input: string | URL) => {
+      const url = new URL(String(input));
+      if (url.pathname === '/api/bundle') {
+        return new Response('not-a-zip', {
+          status: 200,
+          headers: { 'Content-Type': 'application/zip' },
+        });
+      }
+      return Response.json({ error: 'not found' }, { status: 404 });
+    }));
+
+    await expect(
+      contextInstallCloud({
+        cwd,
+        apiKey: 'fc_test_key',
+        rootFiles: 'never',
+      }),
+    ).rejects.toThrow('Bundle download was corrupted, try again.');
+  });
+
+  it('reports status by comparing local and remote catalog revisions', async () => {
+    const { contextStatusCloud } = await import('../context-cloud');
+    await mkdir(join(cwd, '.fragments'), { recursive: true });
+    await writeFile(
+      join(cwd, '.fragments/manifest.json'),
+      JSON.stringify(makeManifest({ catalogRevision: 'old-revision' }), null, 2),
+      'utf-8',
+    );
+
+    await contextStatusCloud({
+      cwd,
+      apiKey: 'fc_test_key',
+    });
+
+    expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('Status: outdated'));
+  });
+
+  it('rejects unsupported bundle schema versions with a clear upgrade message', async () => {
+    const { contextStatusCloud } = await import('../context-cloud');
+    await mkdir(join(cwd, '.fragments'), { recursive: true });
+    await writeFile(
+      join(cwd, '.fragments/manifest.json'),
+      JSON.stringify(makeManifest({ schemaVersion: 2 }), null, 2),
+      'utf-8',
+    );
+
+    await expect(
+      contextStatusCloud({
+        cwd,
+        apiKey: 'fc_test_key',
+      }),
+    ).rejects.toThrow('Unsupported Fragments bundle schemaVersion 2. Upgrade your CLI.');
+  });
+
+  it('rejects unsupported remote schema versions with the same upgrade guidance', async () => {
+    const { contextStatusCloud } = await import('../context-cloud');
+    await mkdir(join(cwd, '.fragments'), { recursive: true });
+    await writeFile(
+      join(cwd, '.fragments/manifest.json'),
+      JSON.stringify(makeManifest(), null, 2),
+      'utf-8',
+    );
+    vi.stubGlobal('fetch', vi.fn(async (input: string | URL) => {
+      const url = new URL(String(input));
+      if (url.pathname === '/api/bundle-artifact') {
+        return Response.json({
+          content: JSON.stringify(makeManifest({ schemaVersion: 2 }), null, 2),
+        });
+      }
+      return new Response(makeBundleZip(), {
+        status: 200,
+        headers: { 'Content-Type': 'application/zip' },
+      });
+    }));
+
+    await expect(
+      contextStatusCloud({
+        cwd,
+        apiKey: 'fc_test_key',
+      }),
+    ).rejects.toThrow('Unsupported Fragments bundle schemaVersion 2. Upgrade your CLI.');
+  });
+});

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

@@ -0,0 +1,185 @@
+import { describe, expect, it } from 'vitest';
+import type { ComponentUsage } from '../../service/enhance/types.js';
+import { computeScore, type GovernanceVerdict } from '@fragments-sdk/govern';
+import {
+  aggregateVerdicts,
+  flattenComponentUsage,
+  buildComplianceSummary,
+} from '../govern-scan-report.js';
+
+function makeVerdict(
+  overrides: Partial<GovernanceVerdict>,
+): GovernanceVerdict {
+  return {
+    passed: true,
+    score: 100,
+    results: [],
+    metadata: {
+      runner: 'cli',
+      duration: 10,
+      nodeCount: 3,
+      componentTypes: [],
+    },
+    ...overrides,
+  };
+}
+
+describe('aggregateVerdicts', () => {
+  it('merges results by validator and computes aggregate metadata', () => {
+    const verdictA = makeVerdict({
+      passed: false,
+      results: [
+        {
+          validator: 'tokens',
+          severity: 'moderate',
+          passed: false,
+          violations: [
+            {
+              nodeId: 'btn-a',
+              nodeType: 'Button',
+              rule: 'tokens/require-design-tokens',
+              severity: 'moderate',
+              message: 'Use design token',
+            },
+          ],
+        },
+        {
+          validator: 'safety',
+          severity: 'serious',
+          passed: true,
+          violations: [],
+        },
+      ],
+      metadata: {
+        runner: 'cli',
+        duration: 25,
+        nodeCount: 4,
+        componentTypes: ['Button', 'Card'],
+      },
+    });
+
+    const verdictB = makeVerdict({
+      passed: false,
+      results: [
+        {
+          validator: 'tokens',
+          severity: 'serious',
+          passed: false,
+          violations: [
+            {
+              nodeId: 'btn-b',
+              nodeType: 'Button',
+              rule: 'tokens/require-design-tokens',
+              severity: 'serious',
+              message: 'Token mismatch',
+            },
+          ],
+        },
+        {
+          validator: 'a11y',
+          severity: 'minor',
+          passed: false,
+          violations: [
+            {
+              nodeId: 'card-a',
+              nodeType: 'Card',
+              rule: 'a11y/standard',
+              severity: 'minor',
+              message: 'Missing aria-label',
+            },
+          ],
+        },
+      ],
+      metadata: {
+        runner: 'cli',
+        duration: 35,
+        nodeCount: 6,
+        componentTypes: ['Button', 'Modal'],
+      },
+    });
+
+    const aggregated = aggregateVerdicts([verdictA, verdictB], computeScore, 'ci');
+
+    expect(aggregated.passed).toBe(false);
+    expect(aggregated.metadata.runner).toBe('ci');
+    expect(aggregated.metadata.duration).toBe(60);
+    expect(aggregated.metadata.nodeCount).toBe(10);
+    expect(aggregated.metadata.componentTypes).toEqual(['Button', 'Card', 'Modal']);
+
+    const tokens = aggregated.results.find((result) => result.validator === 'tokens');
+    expect(tokens).toBeDefined();
+    expect(tokens?.violations).toHaveLength(2);
+    expect(tokens?.severity).toBe('serious');
+    expect(tokens?.passed).toBe(false);
+
+    const allViolations = aggregated.results.flatMap((result) => result.violations);
+    expect(aggregated.score).toBe(computeScore(allViolations));
+  });
+});
+
+describe('flattenComponentUsage', () => {
+  it('flattens and counts usage per component per file', () => {
+    const rootDir = '/repo';
+    const usages: ComponentUsage[] = [
+      {
+        componentName: 'Button',
+        filePath: '/repo/src/app.tsx',
+        line: 4,
+        column: 0,
+        props: { static: {}, dynamic: [], spreads: [] },
+        context: '<Button />',
+        hasSpreadProps: false,
+        isConditional: false,
+      },
+      {
+        componentName: 'Button',
+        filePath: '/repo/src/app.tsx',
+        line: 10,
+        column: 2,
+        props: { static: {}, dynamic: [], spreads: [] },
+        context: '<Button />',
+        hasSpreadProps: false,
+        isConditional: false,
+      },
+      {
+        componentName: 'Card',
+        filePath: '/repo/src/panel.tsx',
+        line: 2,
+        column: 1,
+        props: { static: {}, dynamic: [], spreads: [] },
+        context: '<Card />',
+        hasSpreadProps: false,
+        isConditional: false,
+      },
+    ];
+
+    expect(flattenComponentUsage(usages, rootDir)).toEqual([
+      { component: 'Button', file: 'src/app.tsx', occurrences: 2 },
+      { component: 'Card', file: 'src/panel.tsx', occurrences: 1 },
+    ]);
+  });
+});
+
+describe('buildComplianceSummary', () => {
+  it('derives totals from component usage counts', () => {
+    const summary = buildComplianceSummary({
+      contractCoverage: 80,
+      overallCompliance: 75,
+      components: {
+        Button: { total: 4, passed: 3, violations: 1, score: 75 },
+        Card: { total: 2, passed: 1, violations: 1, score: 50 },
+      },
+      uncontracted: ['Modal'],
+      totalComponents: 3,
+      contractedComponents: 2,
+    });
+
+    expect(summary).toEqual({
+      complianceRate: 75,
+      passingUsages: 4,
+      totalUsages: 6,
+      contractedCount: 2,
+      detectedCount: 3,
+    });
+  });
+});

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

@@ -34,6 +34,7 @@ describe('govern init', () => {
 
       const content = await readFile(configPath, 'utf-8');
       expect(content).toContain('rules');
+      expect(content).not.toContain('cloud: true');
     },
   );