@fragments-sdk/cli 0.15.10 → 0.17.0

package/src/bin.ts

@@ -23,6 +23,10 @@ const EXPERIMENTAL = process.env.FRAGMENTS_EXPERIMENTAL === '1';
 import { validate } from './commands/validate.js';
 import { build } from './commands/build.js';
 import { context } from './commands/context.js';
+import {
+  contextInstallCloud,
+  contextStatusCloud,
+} from './commands/context-cloud.js';
 import { list } from './commands/list.js';
 import { reset } from './commands/reset.js';
 import { compare } from './commands/compare.js';
@@ -45,7 +49,7 @@ import { perf } from './commands/perf.js';
 type DoctorFn = typeof import('./commands/doctor.js')['doctor'];
 import { setup } from './commands/setup.js';
 import { sync } from './commands/sync.js';
-import { governCheck, governInit, governReport, governConnect } from './commands/govern.js';
+import { governCheck, governInit, governReport } from './commands/govern.js';
 import { migrateContract } from './commands/migrate-contract.js';
 
 // Import existing commands that were already extracted
@@ -157,8 +161,8 @@ program
 // CONTEXT COMMAND
 // ============================================================================
 program
-  .command('context')
-  .description('Generate AI-ready context for your design system')
+  .command('context [action]')
+  .description('Generate AI-ready context or install a Fragments Cloud bundle')
   .option('-c, --config <path>', 'Path to config file')
   .option('-i, --input <path>', `Path to ${BRAND.outFile} (builds if not provided)`)
   .option('-f, --format <format>', 'Output format (markdown/json)', 'markdown')
@@ -166,8 +170,47 @@ program
   .option('--code', 'Include code examples')
   .option('--relations', 'Include component relationships')
   .option('--tokens', 'Only output token estimate')
-  .action(async (options) => {
+  .option('--cloud', 'Use Fragments Cloud bundle endpoints')
+  .option('--api-key <key>', 'Fragments Cloud API key (or use FRAGMENTS_API_KEY)')
+  .option('--targets <list>', 'Comma-separated helper targets (cursor,agents,claude,copilot)')
+  .option('--cwd <path>', 'Project root for install/status')
+  .option('--dry-run', 'Preview file writes without modifying the repo')
+  .option('-y, --yes', 'Non-interactive mode')
+  .option('--root-files <mode>', 'Root instruction file mode (prompt|never|patch)')
+  .option('--gitignore-fragments', 'Add .fragments/ to .gitignore after install')
+  .action(async (action, options) => {
     try {
+      if (options.cloud && action === 'install') {
+        await contextInstallCloud({
+          apiKey: options.apiKey,
+          targets: options.targets,
+          cwd: options.cwd,
+          dryRun: options.dryRun,
+          yes: options.yes,
+          rootFiles: options.rootFiles,
+          gitignoreFragments: options.gitignoreFragments,
+        });
+        return;
+      }
+
+      if (options.cloud && action === 'status') {
+        await contextStatusCloud({
+          apiKey: options.apiKey,
+          cwd: options.cwd,
+        });
+        return;
+      }
+
+      if (action === 'install' || action === 'status') {
+        throw new Error(
+          `context ${action} requires --cloud`,
+        );
+      }
+
+      if (action && action !== 'install' && action !== 'status') {
+        throw new Error(`Unknown context action: ${action}`);
+      }
+
       const result = await context({
         config: options.config,
         input: options.input,
@@ -885,35 +928,8 @@ const initCmd = program
   .option('--api-key <key>', 'API key for AI enrichment')
   .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 — 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,
-          port: options.port ? Number(options.port) : undefined,
-          authOnly: options.authOnly,
-          skipCheck: options.skipCheck,
-        });
-        return;
-      }
-
       const { init } = await import('./commands/init.js');
       const result = await init({
         projectRoot: process.cwd(),
@@ -1036,28 +1052,6 @@ 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
 // ============================================================================
@@ -1374,25 +1368,17 @@ governCmd
     }
   });
 
-governCmd
-  .command('connect')
-  .description('Connect your project to the Fragments Govern cloud dashboard')
-  .action(async () => {
-    try {
-      await governConnect();
-    } catch (error) {
-      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
-      process.exit(1);
-    }
-  });
-
 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('-r, --report <path>', 'Write an aggregated machine-readable JSON report')
   .option('-q, --quiet', 'Suppress non-error output')
+  .option('--api-key <key>', 'Fragments Cloud API key — report findings to Cloud')
+  .option('--cloud-url <url>', 'Fragments Cloud URL (default: https://app.usefragments.com)')
+  .option('--diff [base]', 'Only scan files changed vs a base ref (default: auto-detect merge base)')
   .action(async (options) => {
     try {
       const { governScan } = await import('./commands/govern-scan.js');
@@ -1400,7 +1386,11 @@ governCmd
         dir: options.dir,
         config: options.config,
         format: options.format,
+        report: options.report,
         quiet: options.quiet,
+        apiKey: options.apiKey ?? process.env.FRAGMENTS_API_KEY,
+        cloudUrl: options.cloudUrl ?? process.env.FRAGMENTS_CLOUD_URL,
+        diff: options.diff,
       });
       process.exit(exitCode);
     } catch (error) {
@@ -1431,28 +1421,5 @@ 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-26T14:38:30.456Z"
+    "extractedAt": "2026-04-04T15:06:36.231Z"
   }
 }

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-26T14:38:30.457Z"
+    "extractedAt": "2026-04-04T15:06:36.234Z"
   }
 }

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.');
+  });
+});