@fragments-sdk/cli 0.14.2 → 0.15.0

package/src/commands/enhance.ts

@@ -266,6 +266,7 @@ export async function enhance(options: EnhanceOptions = {}): Promise<EnhanceResu
         if (fs.existsSync(srcPath)) {
           const extraction = await extractPropsFromFile(srcPath, {
             propsTypeName: `${compName}Props`,
+            componentName: compName,
           });
           if (extraction.success) {
             propsExtractions.set(compName, extraction);
@@ -763,7 +764,8 @@ function calculateCost(provider: AIProvider, tokens: number): number {
  */
 async function findFragmentFiles(dir: string): Promise<string[]> {
   const fg = await import('fast-glob');
-  return fg.default(['**/*.fragment.tsx', '**/*.fragment.ts'], {
+  // Search for both .contract.json (preferred) and legacy .fragment.tsx files
+  return fg.default(['**/*.contract.json', '**/*.fragment.tsx', '**/*.fragment.ts'], {
     cwd: dir,
     absolute: true,
     ignore: ['**/node_modules/**', '**/dist/**'],

package/src/commands/govern-scan.ts

@@ -0,0 +1,386 @@
+/**
+ * govern scan / govern watch — Zero-config governance scanning
+ *
+ * Parses real JSX/TSX files via the existing codebase scanner, converts
+ * component usages to UISpec, and runs governance checks per file.
+ * Optionally submits results to Fragments Cloud.
+ */
+
+import pc from 'picocolors';
+import { resolve, relative } from 'node:path';
+import { existsSync } from 'node:fs';
+import { BRAND } from '../core/index.js';
+import type { ComponentUsage } from '../service/enhance/types.js';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface GovernScanOptions {
+  /** Root directory to scan (default: auto-detect) */
+  dir?: string;
+  /** Path to govern.config.ts */
+  config?: string;
+  /** Output format */
+  format?: 'summary' | 'json' | 'sarif';
+  /** Suppress non-error output */
+  quiet?: boolean;
+}
+
+export interface GovernWatchOptions extends GovernScanOptions {
+  /** Debounce interval in ms (default: 300) */
+  debounce?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Scan defaults — applied when no config file exists
+// ---------------------------------------------------------------------------
+
+const SCAN_DEFAULT_RULES: Record<string, boolean | object> = {
+  'safety/no-dangerous-html': true,
+  'safety/sanitize-hrefs': true,
+  'safety/no-inline-scripts': true,
+  'safety/no-exposed-secrets': true,
+  'tokens/require-design-tokens': true,
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Auto-detect root directory by looking for common React project dirs
+ */
+function detectRootDir(cwd: string): string {
+  const candidates = ['src', 'app', 'pages', 'components'];
+  for (const dir of candidates) {
+    if (existsSync(resolve(cwd, dir))) {
+      return cwd;
+    }
+  }
+  return cwd;
+}
+
+/**
+ * Group component usages by their source file
+ */
+function groupByFile(usages: ComponentUsage[]): Map<string, ComponentUsage[]> {
+  const grouped = new Map<string, ComponentUsage[]>();
+  for (const usage of usages) {
+    const existing = grouped.get(usage.filePath);
+    if (existing) {
+      existing.push(usage);
+    } else {
+      grouped.set(usage.filePath, [usage]);
+    }
+  }
+  return grouped;
+}
+
+// ---------------------------------------------------------------------------
+// governScan
+// ---------------------------------------------------------------------------
+
+export async function governScan(
+  options: GovernScanOptions = {},
+): Promise<{ exitCode: number }> {
+  const {
+    loadPolicy,
+    createEngine,
+    buildAdaptersFromConfig,
+    createCloudAdapter,
+    formatVerdict,
+  } = await import('@fragments-sdk/govern');
+
+  const { scanCodebase } = await import(
+    '../service/enhance/codebase-scanner.js'
+  );
+  const { usagesToSpec } = await import(
+    '../service/enhance/converter.js'
+  );
+
+  const format = options.format ?? 'summary';
+  const quiet = options.quiet ?? false;
+
+  if (!quiet) {
+    console.log(pc.cyan(`\n${BRAND.name} Governance Scan\n`));
+  }
+
+  // 1. Resolve root directory
+  const rootDir = resolve(options.dir ?? detectRootDir(process.cwd()));
+  if (!quiet) {
+    console.log(pc.dim(`  Root: ${rootDir}\n`));
+  }
+
+  // 2. Load policy — use scan defaults if no config exists
+  let policy = await loadPolicy(options.config);
+  const hasRules = Object.keys(policy.rules).length > 0;
+
+  if (!hasRules) {
+    policy = { ...policy, rules: SCAN_DEFAULT_RULES };
+    if (!quiet) {
+      console.log(pc.dim('  No config found — using scan defaults (safety + tokens)\n'));
+    }
+  }
+
+  // 3. Build adapters. Auto-add cloud if FRAGMENTS_API_KEY is set
+  const adapters = buildAdaptersFromConfig(policy.audit);
+  const hasCloudAdapter = adapters.length > 0 && policy.audit?.cloud;
+  if (!hasCloudAdapter && process.env.FRAGMENTS_API_KEY) {
+    adapters.push(createCloudAdapter());
+    if (!quiet) {
+      console.log(pc.dim('  Cloud audit enabled (FRAGMENTS_API_KEY detected)\n'));
+    }
+  }
+
+  // 4. Create engine
+  const engine = createEngine(policy, adapters);
+
+  // 5. Scan codebase
+  if (!quiet) {
+    console.log(pc.dim('  Scanning files...\n'));
+  }
+
+  const analysis = await scanCodebase({
+    rootDir,
+    useCache: true,
+    onProgress: quiet
+      ? undefined
+      : (progress) => {
+          if (progress.phase === 'scanning') {
+            process.stdout.write(
+              `\r  ${pc.dim(`[${progress.current}/${progress.total}]`)} ${pc.dim(relative(rootDir, progress.currentFile))}`,
+            );
+          }
+        },
+  });
+
+  if (!quiet) {
+    // Clear progress line
+    process.stdout.write('\r' + ' '.repeat(80) + '\r');
+    console.log(
+      pc.dim(`  Scanned ${analysis.totalFiles} files, found ${analysis.totalComponents} component types\n`),
+    );
+  }
+
+  // 6. Collect all usages across components
+  const allUsages: ComponentUsage[] = [];
+  for (const comp of Object.values(analysis.components)) {
+    allUsages.push(...comp.usages);
+  }
+
+  if (allUsages.length === 0) {
+    if (!quiet) {
+      console.log(pc.yellow('  No component usages found.\n'));
+    }
+    return { exitCode: 0 };
+  }
+
+  // 7. Group by file and run checks
+  const grouped = groupByFile(allUsages);
+  let totalFiles = 0;
+  let passedFiles = 0;
+  let totalViolations = 0;
+  const violationCounts = new Map<string, number>();
+
+  for (const [filePath, usages] of grouped) {
+    const spec = usagesToSpec(usages, filePath, rootDir);
+    const relPath = relative(rootDir, filePath);
+
+    const verdict = await engine.check(spec, {
+      runner: 'cli',
+      input: relPath,
+    });
+
+    totalFiles++;
+
+    if (verdict.passed) {
+      passedFiles++;
+    } else {
+      if (!quiet) {
+        console.log(pc.red(`  ✗ ${relPath}`));
+        if (format === 'summary') {
+          for (const result of verdict.results) {
+            for (const v of result.violations) {
+              const count = violationCounts.get(v.rule) ?? 0;
+              violationCounts.set(v.rule, count + 1);
+              totalViolations++;
+              console.log(
+                pc.dim(`    ${v.severity} `) +
+                pc.yellow(v.rule) +
+                pc.dim(` — ${v.message}`),
+              );
+              if (v.nodeId) {
+                console.log(pc.dim(`      at ${v.nodeId}`));
+              }
+            }
+          }
+        }
+      }
+    }
+
+    if (verdict.passed && !quiet && format === 'summary') {
+      console.log(pc.green(`  ✓ ${relPath}`) + pc.dim(` (${usages.length} components, score: ${verdict.score}/100)`));
+    }
+
+    // JSON/SARIF: print per-file
+    if (format === 'json' || format === 'sarif') {
+      const output = formatVerdict(verdict, format);
+      console.log(output);
+    }
+  }
+
+  // 8. Summary
+  if (!quiet && format === 'summary') {
+    console.log(pc.dim('\n  ─────────────────────────────────────\n'));
+    console.log(`  Files checked:  ${totalFiles}`);
+    console.log(`  Passed:         ${passedFiles}/${totalFiles}`);
+    console.log(`  Violations:     ${totalViolations}`);
+
+    if (violationCounts.size > 0) {
+      console.log(pc.dim('\n  Top violations:'));
+      const sorted = [...violationCounts.entries()].sort((a, b) => b[1] - a[1]);
+      for (const [rule, count] of sorted.slice(0, 5)) {
+        console.log(pc.dim(`    ${count}× `) + pc.yellow(rule));
+      }
+    }
+
+    console.log();
+
+    if (passedFiles === totalFiles) {
+      console.log(pc.green(`  ✓ All files passed governance checks\n`));
+    } else {
+      console.log(
+        pc.red(`  ✗ ${totalFiles - passedFiles} file(s) failed governance checks\n`),
+      );
+    }
+  }
+
+  return { exitCode: passedFiles === totalFiles ? 0 : 1 };
+}
+
+// ---------------------------------------------------------------------------
+// governWatch
+// ---------------------------------------------------------------------------
+
+export async function governWatch(
+  options: GovernWatchOptions = {},
+): Promise<void> {
+  const {
+    loadPolicy,
+    createEngine,
+    buildAdaptersFromConfig,
+    createCloudAdapter,
+    formatVerdict,
+  } = await import('@fragments-sdk/govern');
+
+  const { scanFile } = await import('../service/enhance/scanner.js');
+  const { usagesToSpec } = await import(
+    '../service/enhance/converter.js'
+  );
+
+  const quiet = options.quiet ?? false;
+  const debounceMs = options.debounce ?? 300;
+  const format = options.format ?? 'summary';
+
+  // 1. Run initial scan
+  console.log(pc.cyan(`\n${BRAND.name} Governance Watch\n`));
+
+  const { exitCode } = await governScan(options);
+  if (!quiet) {
+    console.log(
+      pc.dim(`  Initial scan ${exitCode === 0 ? 'passed' : 'completed with violations'}\n`),
+    );
+  }
+
+  // 2. Set up engine for incremental checks
+  const rootDir = resolve(options.dir ?? detectRootDir(process.cwd()));
+  let policy = await loadPolicy(options.config);
+  if (Object.keys(policy.rules).length === 0) {
+    policy = { ...policy, rules: SCAN_DEFAULT_RULES };
+  }
+  const adapters = buildAdaptersFromConfig(policy.audit);
+  if (!adapters.some(() => policy.audit?.cloud) && process.env.FRAGMENTS_API_KEY) {
+    adapters.push(createCloudAdapter());
+  }
+  const engine = createEngine(policy, adapters);
+
+  // 3. Watch for changes
+  console.log(pc.dim('  Watching for changes... (Ctrl+C to stop)\n'));
+
+  const chokidar = await import('chokidar');
+
+  const watcher = chokidar.watch(
+    ['**/*.tsx', '**/*.ts', '**/*.jsx', '**/*.js'],
+    {
+      cwd: rootDir,
+      ignoreInitial: true,
+      ignored: [
+        '**/node_modules/**',
+        '**/dist/**',
+        '**/build/**',
+        '**/.next/**',
+        '**/*.test.*',
+        '**/*.spec.*',
+        '**/*.stories.*',
+      ],
+      awaitWriteFinish: { stabilityThreshold: debounceMs },
+    },
+  );
+
+  const handleChange = async (changedRelPath: string) => {
+    const absolutePath = resolve(rootDir, changedRelPath);
+
+    try {
+      const { usages } = await scanFile(absolutePath);
+
+      if (usages.length === 0) {
+        if (!quiet) {
+          console.log(pc.dim(`  ○ ${changedRelPath} — no component usages`));
+        }
+        return;
+      }
+
+      const spec = usagesToSpec(usages, absolutePath, rootDir);
+      const verdict = await engine.check(spec, {
+        runner: 'cli',
+        input: changedRelPath,
+      });
+
+      if (verdict.passed) {
+        console.log(
+          pc.green(`  ✓ ${changedRelPath}`) +
+          pc.dim(` (${usages.length} components, score: ${verdict.score}/100)`),
+        );
+      } else {
+        console.log(pc.red(`  ✗ ${changedRelPath}`));
+        if (format === 'summary') {
+          for (const result of verdict.results) {
+            for (const v of result.violations) {
+              console.log(
+                pc.dim(`    ${v.severity} `) +
+                pc.yellow(v.rule) +
+                pc.dim(` — ${v.message}`),
+              );
+            }
+          }
+        } else {
+          console.log(formatVerdict(verdict, format));
+        }
+      }
+    } catch (error) {
+      if (!quiet) {
+        console.log(
+          pc.dim(`  ⚠ ${changedRelPath} — `) +
+          pc.yellow(error instanceof Error ? error.message : 'parse error'),
+        );
+      }
+    }
+  };
+
+  watcher.on('change', handleChange);
+  watcher.on('add', handleChange);
+
+  // Keep process alive
+  await new Promise(() => {});
+}

package/src/commands/govern.ts

@@ -95,7 +95,7 @@ export async function governConnect(): Promise<void> {
   // ── Step 1: Get API key ──────────────────────────────────────────────────
   console.log(pc.bold('  Step 1 of 3: Get your API key\n'));
 
-  const dashboardUrl = `${cloudUrl}/dashboard/settings`;
+  const dashboardUrl = `${cloudUrl}/api-keys`;
   console.log(pc.dim(`  → Opening the dashboard in your browser...`));
   console.log(pc.dim(`    Copy your API key from Settings → API Keys\n`));
 
@@ -226,7 +226,7 @@ export async function governConnect(): Promise<void> {
   // ── Done ────────────────────────────────────────────────────────────────
   console.log(pc.dim('\n  ─────────────────────────────────────\n'));
   console.log(pc.green('  ✓ All set!') + ' Run `fragments govern check` to send your first audit.\n');
-  console.log(pc.dim(`  Dashboard: ${cloudUrl}/dashboard\n`));
+  console.log(pc.dim(`  Dashboard: ${cloudUrl}/overview\n`));
 }
 
 // ---------------------------------------------------------------------------

package/src/commands/init.ts

@@ -20,6 +20,49 @@ import {
   addTranspilePackages,
 } from "./setup.js";
 
+/**
+ * Detect existing UI component libraries by reading package.json.
+ * Returns the library display name or null if none found.
+ */
+async function detectExistingUILibrary(projectRoot: string): Promise<string | null> {
+  let pkg: Record<string, unknown>;
+  try {
+    const raw = await readFile(join(projectRoot, "package.json"), "utf-8");
+    pkg = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  const allDeps: Record<string, string> = {
+    ...(pkg.dependencies as Record<string, string> || {}),
+    ...(pkg.devDependencies as Record<string, string> || {}),
+  };
+
+  // shadcn/ui: tailwindcss present + components/ui/ directory
+  if (allDeps["tailwindcss"]) {
+    const shadcnFiles = await fg(["**/components/ui/*.tsx", "**/components/ui/*.ts"], {
+      cwd: projectRoot,
+      ignore: ["**/node_modules/**"],
+    });
+    if (shadcnFiles.length > 0) {
+      return "shadcn/ui";
+    }
+  }
+
+  if (allDeps["@mui/material"]) return "Material UI";
+  if (allDeps["@chakra-ui/react"]) return "Chakra UI";
+  if (allDeps["@mantine/core"]) return "Mantine";
+  if (allDeps["antd"]) return "Ant Design";
+
+  // Radix UI: has @radix-ui/react-* packages but NOT @fragments-sdk/ui
+  const hasRadix = Object.keys(allDeps).some((dep) => dep.startsWith("@radix-ui/react-"));
+  if (hasRadix && !allDeps["@fragments-sdk/ui"]) {
+    return "Radix UI";
+  }
+
+  return null;
+}
+
 export interface InitOptions {
   /** Project root directory */
   projectRoot?: string;
@@ -43,6 +86,10 @@ export interface InitOptions {
   apiKey?: string;
   /** Override AI model for enrichment */
   model?: string;
+  /** Generate metadata/governance files without injecting runtime UI */
+  metadataOnly?: boolean;
+  /** Alias for metadataOnly */
+  govern?: boolean;
 }
 
 export interface InitResult {
@@ -342,6 +389,49 @@ export default defineFragment({
 `;
 }
 
+function generateExampleContract(): string {
+  return JSON.stringify({
+    $schema: 'https://usefragments.com/schemas/contract.v1.json',
+    name: 'Button',
+    description: 'Interactive button for triggering actions',
+    category: 'Actions',
+    status: 'stable',
+    sourcePath: 'src/components/Button.tsx',
+    exportName: 'Button',
+    propsSummary: [
+      'variant: primary|secondary|ghost (default: primary)',
+      'size: sm|md|lg (default: md)',
+      'children: node (required)',
+    ],
+    props: {
+      children: { type: 'node', required: true, description: 'Button label content' },
+      variant: {
+        type: 'enum',
+        values: ['primary', 'secondary', 'ghost'],
+        default: 'primary',
+        description: 'Visual style variant',
+      },
+      size: {
+        type: 'enum',
+        values: ['sm', 'md', 'lg'],
+        default: 'md',
+        description: 'Button size',
+      },
+    },
+    usage: {
+      when: ['Triggering an action (save, submit, delete)', 'Form submission', 'Opening dialogs or menus'],
+      whenNot: ['Simple navigation (use Link)', 'Toggling state (use Switch)'],
+      guidelines: ['Use Primary for the main action in a context', 'Only one Primary button per section'],
+    },
+    examples: [
+      { name: 'Primary', description: 'Default action button', code: '<Button variant="primary">Save Changes</Button>' },
+      { name: 'Secondary', description: 'Less prominent action', code: '<Button variant="secondary">Cancel</Button>' },
+      { name: 'Ghost', description: 'Minimal visual weight', code: '<Button variant="ghost">Learn More</Button>' },
+    ],
+    provenance: { source: 'manual', verified: false },
+  }, null, 2) + '\n';
+}
+
 /**
  * Start the dev server
  */
@@ -539,7 +629,7 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
     const relScanPath = relative(projectRoot, scanPath);
     const configPath = join(projectRoot, BRAND.configFile);
     const configContent = generateConfig({
-      includePaths: [`${relScanPath}/**/*.fragment.tsx`],
+      includePaths: [`${relScanPath}/**/*.contract.json`],
       componentPaths: [`${relScanPath}/**/*.tsx`],
       framework: "react",
     });
@@ -642,7 +732,7 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
 
   // Step 5: Create configuration file
   const includePaths: string[] = [
-    `${componentPath}/**/*.fragment.tsx`,
+    `${componentPath}/**/*.contract.json`,
   ];
 
   if (scenario === 'stories') {
@@ -667,33 +757,62 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
   }
 
   // Step 6: Auto-inject styles + framework config
-  const entryFile = await findEntryFile(projectRoot, framework);
+  // Detect existing UI libraries — skip @fragments-sdk/ui runtime if one is found
+  const detectedUILib = await detectExistingUILibrary(projectRoot);
 
-  if (entryFile) {
-    try {
-      const stylesResult = await addStylesImport(projectRoot, entryFile);
-      if (stylesResult.modified) {
-        console.log(pc.green(`  ✓ Added styles import to ${entryFile}`));
-      } else {
-        console.log(pc.dim(`  · ${stylesResult.message}`));
-      }
-    } catch (e) {
-      errors.push(`Failed to add styles import: ${e instanceof Error ? e.message : e}`);
+  // Check if @fragments-sdk/ui is already a dependency
+  let hasFragmentsUI = false;
+  try {
+    const pkgRaw = await readFile(join(projectRoot, "package.json"), "utf-8");
+    const pkgJson = JSON.parse(pkgRaw);
+    const allDeps = {
+      ...(pkgJson.dependencies || {}),
+      ...(pkgJson.devDependencies || {}),
+    };
+    hasFragmentsUI = !!allDeps["@fragments-sdk/ui"];
+  } catch {
+    // no package.json — can't determine, default to injecting
+  }
+
+  const explicitMetadataOnly = !!options.metadataOnly || !!options.govern;
+  const skipUIRuntime = explicitMetadataOnly || (detectedUILib !== null && !hasFragmentsUI);
+
+  if (skipUIRuntime) {
+    if (explicitMetadataOnly) {
+      console.log(pc.dim(`  · Metadata-only mode — skipping @fragments-sdk/ui runtime setup`));
+    } else {
+      console.log(pc.dim(`  · Detected ${detectedUILib} — skipping @fragments-sdk/ui runtime setup`));
     }
+    console.log(pc.dim(`  · Run '${BRAND.cliCommand} setup' if you want to add @fragments-sdk/ui later`));
+  } else {
+    const entryFile = await findEntryFile(projectRoot, framework);
+
+    if (entryFile) {
+      try {
+        const stylesResult = await addStylesImport(projectRoot, entryFile);
+        if (stylesResult.modified) {
+          console.log(pc.green(`  ✓ Added styles import to ${entryFile}`));
+        } else {
+          console.log(pc.dim(`  · ${stylesResult.message}`));
+        }
+      } catch (e) {
+        errors.push(`Failed to add styles import: ${e instanceof Error ? e.message : e}`);
+      }
 
-    try {
-      const providerResult = await addThemeProvider(projectRoot, entryFile, framework);
-      if (providerResult.modified) {
-        console.log(pc.green(`  ✓ Added ThemeProvider to ${entryFile}`));
-      } else {
-        console.log(pc.dim(`  · ${providerResult.message}`));
+      try {
+        const providerResult = await addThemeProvider(projectRoot, entryFile, framework);
+        if (providerResult.modified) {
+          console.log(pc.green(`  ✓ Added ThemeProvider to ${entryFile}`));
+        } else {
+          console.log(pc.dim(`  · ${providerResult.message}`));
+        }
+      } catch (e) {
+        errors.push(`Failed to add ThemeProvider: ${e instanceof Error ? e.message : e}`);
       }
-    } catch (e) {
-      errors.push(`Failed to add ThemeProvider: ${e instanceof Error ? e.message : e}`);
+    } else {
+      console.log(pc.yellow(`  ! Could not detect entry file — add styles import manually`));
+      console.log(pc.dim(`    import '@fragments-sdk/ui/styles'`));
     }
-  } else {
-    console.log(pc.yellow(`  ! Could not detect entry file — add styles import manually`));
-    console.log(pc.dim(`    import '@fragments-sdk/ui/styles'`));
   }
 
   // Next.js: add transpilePackages
@@ -727,13 +846,13 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
       );
 
       await writeFile(
-        join(exampleDir, "Button.fragment.tsx"),
-        generateExampleFragment(),
+        join(exampleDir, "Button.contract.json"),
+        generateExampleContract(),
         "utf-8"
       );
       console.log(
         pc.green(
-          `  ✓ Created ${relative(projectRoot, join(exampleDir, "Button.fragment.tsx"))}`
+          `  ✓ Created ${relative(projectRoot, join(exampleDir, "Button.contract.json"))}`
         )
       );
     } catch (e) {
@@ -775,9 +894,14 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
 
     if (startServer) {
       startDevServer(projectRoot);
+    } else if (skipUIRuntime) {
+      console.log(`  ${pc.bold("Get started:")}`);
+      console.log(`    ${pc.dim("$")} ${BRAND.cliCommand} build`);
+      console.log(`    ${pc.dim("$")} ${BRAND.cliCommand} verify --ci`);
+      console.log();
     } else {
       console.log(`  ${pc.bold("Get started:")}`);
-      console.log(`    ${pc.dim("$")} ${BRAND.cliCommand} dev`);
+      console.log(`    ${pc.dim("$")} ${BRAND.cliCommand} build`);
       console.log();
 
       if (!options.configure) {