@fragments-sdk/cli 0.14.3 → 0.15.1

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,565 @@
+/**
+ * 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,
+    computeComponentHealth,
+  } = 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. Extract code tokens for cloud ingest
+  let codeTokens: string | undefined;
+  if (process.env.FRAGMENTS_API_KEY) {
+    codeTokens = await extractCodeTokens(rootDir, options.config, quiet);
+  }
+
+  // 3b. Load contract registry for governance + cloud ingest (if fragments.json exists)
+  let contractRegistry: string | undefined;
+  let registryMap: Record<string, unknown> | undefined;
+  {
+    const { readFileSync, existsSync } = await import('node:fs');
+    const fragmentsJsonPath = resolve(rootDir, 'fragments.json');
+    if (existsSync(fragmentsJsonPath)) {
+      try {
+        const raw = readFileSync(fragmentsJsonPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed.fragments && Array.isArray(parsed.fragments)) {
+          // Build name-keyed map for engine registry injection
+          const map: Record<string, unknown> = {};
+          for (const f of parsed.fragments) {
+            if (f.meta?.name) {
+              map[f.meta.name] = f;
+            }
+          }
+          registryMap = map;
+
+          if (process.env.FRAGMENTS_API_KEY) {
+            contractRegistry = JSON.stringify({ fragments: parsed.fragments });
+          }
+          if (!quiet) {
+            console.log(pc.dim(`  Contract registry loaded (${parsed.fragments.length} components)\n`));
+          }
+        }
+      } catch {
+        // Invalid fragments.json — skip
+      }
+    }
+  }
+
+  // 4. 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({ codeTokens, contractRegistry }));
+    if (!quiet) {
+      console.log(pc.dim('  Cloud audit enabled (FRAGMENTS_API_KEY detected)\n'));
+    }
+  }
+
+  // 5. Create engine (with registry for contract-aware validators)
+  const engine = createEngine(
+    policy,
+    adapters,
+    registryMap
+      ? { registry: { fragments: registryMap as Record<string, Record<string, unknown>> } }
+      : undefined,
+  );
+
+  // 6. 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`),
+    );
+  }
+
+  // 7. 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 };
+  }
+
+  // 8. 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>();
+  const allVerdicts: Awaited<ReturnType<typeof engine.check>>[] = [];
+
+  // Build per-file usage snapshot for cloud
+  const usageSnapshot: Array<{
+    file: string;
+    components: Array<{
+      name: string;
+      line: number;
+      props: { static: Record<string, unknown>; dynamic: string[] };
+    }>;
+  }> = [];
+
+  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,
+    });
+    allVerdicts.push(verdict);
+
+    // Collect per-file usage snapshot
+    usageSnapshot.push({
+      file: relPath,
+      components: usages.map((u) => ({
+        name: u.componentName,
+        line: u.line,
+        props: {
+          static: u.props.static,
+          dynamic: u.props.dynamic,
+        },
+      })),
+    });
+
+    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);
+    }
+  }
+
+  // 8b. Compute component health
+  const health = computeComponentHealth(allVerdicts, registryMap ?? {});
+
+  // 9. 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));
+      }
+    }
+
+    // Component health
+    console.log(pc.dim('\n  Component Health:'));
+    console.log(`    Contract coverage:  ${health.contractCoverage}% (${health.contractedComponents}/${health.totalComponents})`);
+    console.log(`    Compliance rate:    ${health.overallCompliance}%`);
+
+    if (health.uncontracted.length > 0) {
+      console.log(pc.dim(`    Uncontracted:       ${health.uncontracted.slice(0, 5).join(', ')}${health.uncontracted.length > 5 ? ` (+${health.uncontracted.length - 5} more)` : ''}`));
+    }
+
+    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`),
+      );
+    }
+  }
+
+  // 10. Push component usage snapshot + health to Cloud (if API key set)
+  if (process.env.FRAGMENTS_API_KEY && usageSnapshot.length > 0) {
+    try {
+      const apiKey = process.env.FRAGMENTS_API_KEY;
+      const url = process.env.FRAGMENTS_URL ?? 'https://app.usefragments.com';
+      await fetch(`${url}/api/ingest`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          componentUsage: JSON.stringify(usageSnapshot),
+          componentHealth: JSON.stringify(health),
+        }),
+      });
+    } catch {
+      // Non-critical — don't fail the scan
+    }
+  }
+
+  return { exitCode: passedFiles === totalFiles ? 0 : 1 };
+}
+
+// ---------------------------------------------------------------------------
+// Token extraction for cloud ingest
+// ---------------------------------------------------------------------------
+
+/**
+ * Auto-detect and extract code tokens to send alongside governance verdicts.
+ * Tries: 1) tokens config from fragments.config.ts, 2) Tailwind config.
+ * Returns a flat JSON string of token name → value, or undefined if nothing found.
+ */
+async function extractCodeTokens(
+  rootDir: string,
+  configPath?: string,
+  quiet?: boolean,
+): Promise<string | undefined> {
+  try {
+    // 1. Try fragments.config.ts tokens config
+    try {
+      const { loadConfig } = await import('../core/node.js');
+      const { parseTokenFiles } = await import('../service/index.js');
+
+      const { config, configDir } = await loadConfig(configPath);
+      if (config.tokens?.include?.length) {
+        const result = await parseTokenFiles(config.tokens, configDir);
+        if (result.tokens.length > 0) {
+          const flat: Record<string, string> = {};
+          for (const token of result.tokens) {
+            flat[token.name] = token.resolvedValue;
+          }
+          if (!quiet) {
+            console.log(
+              pc.dim(`  Extracted ${result.tokens.length} code tokens from config\n`),
+            );
+          }
+          return JSON.stringify(flat);
+        }
+      }
+    } catch {
+      // No config or no tokens section — fall through
+    }
+
+    // 2. Try Tailwind config
+    const {
+      findTailwindConfig,
+      loadTailwindConfig,
+    } = await import('../service/token-normalizer.js');
+
+    const tailwindPath = findTailwindConfig(rootDir);
+    if (tailwindPath) {
+      const tokens = await loadTailwindConfig(tailwindPath);
+      if (tokens.length > 0) {
+        const flat: Record<string, string> = {};
+        for (const token of tokens) {
+          flat[token.name] = token.value;
+        }
+        if (!quiet) {
+          console.log(
+            pc.dim(`  Extracted ${tokens.length} tokens from Tailwind config\n`),
+          );
+        }
+        return JSON.stringify(flat);
+      }
+    }
+  } catch (error) {
+    if (!quiet) {
+      console.log(
+        pc.dim(
+          `  Token extraction skipped: ${error instanceof Error ? error.message : 'unknown error'}\n`,
+        ),
+      );
+    }
+  }
+
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// 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

@@ -62,14 +62,77 @@ export async function governCheck(options: GovernCheckOptions = {}): Promise<{ e
 
 export async function governInit(options: GovernInitOptions = {}): Promise<void> {
   const { writeFile } = await import('node:fs/promises');
+  const { existsSync } = await import('node:fs');
   const { resolve } = await import('node:path');
   const { generateConfigTemplate } = await import('@fragments-sdk/govern');
+  const { findTailwindConfig } = await import(
+    '../service/token-normalizer.js'
+  );
+
+  const cwd = process.cwd();
+
+  // Auto-detect token sources
+  const detected: { tokenIncludes: string[]; projectType: string } = {
+    tokenIncludes: [],
+    projectType: 'unknown',
+  };
+
+  // Check for Tailwind
+  const tailwindPath = findTailwindConfig(cwd);
+  if (tailwindPath) {
+    const { relative } = await import('node:path');
+    detected.tokenIncludes.push(relative(cwd, tailwindPath));
+    detected.projectType = 'tailwind';
+    console.log(pc.dim(`  Detected Tailwind config: ${detected.tokenIncludes[0]}`));
+  }
+
+  // Check for common SCSS/CSS token files
+  if (detected.tokenIncludes.length === 0) {
+    const candidates = [
+      'src/styles/tokens.scss',
+      'src/styles/variables.scss',
+      'src/styles/theme.scss',
+      'src/tokens.css',
+      'src/styles/tokens.css',
+      'src/styles/variables.css',
+      'styles/tokens.scss',
+      'styles/variables.scss',
+      'tokens.json',
+      'src/tokens.json',
+    ];
+    for (const candidate of candidates) {
+      if (existsSync(resolve(cwd, candidate))) {
+        detected.tokenIncludes.push(candidate);
+        detected.projectType = candidate.endsWith('.scss')
+          ? 'scss'
+          : candidate.endsWith('.json')
+            ? 'dtcg'
+            : 'css';
+        console.log(pc.dim(`  Detected token source: ${candidate}`));
+      }
+    }
+  }
+
+  if (detected.tokenIncludes.length === 0) {
+    console.log(pc.dim('  No token sources auto-detected. You can add them manually.'));
+  }
 
   const outputPath = resolve(options.output ?? 'fragments.config.ts');
-  const template = generateConfigTemplate();
+  const template = generateConfigTemplate({ tokenIncludes: detected.tokenIncludes });
 
   await writeFile(outputPath, template, 'utf-8');
-  console.log(pc.green(`✓ Created ${outputPath}\n`));
+  console.log(pc.green(`\n✓ Created ${outputPath}\n`));
+
+  if (detected.tokenIncludes.length > 0) {
+    console.log(
+      pc.dim(`  Token sources configured: ${detected.tokenIncludes.join(', ')}`),
+    );
+  }
+  console.log(
+    pc.dim('  Run ') +
+    pc.cyan('fragments govern scan') +
+    pc.dim(' to check your project.\n'),
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -95,7 +158,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 +289,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`));
 }
 
 // ---------------------------------------------------------------------------