@fragments-sdk/cli 0.15.0 → 0.15.2

package/src/commands/govern-scan.ts

@@ -90,6 +90,7 @@ export async function governScan(
     buildAdaptersFromConfig,
     createCloudAdapter,
     formatVerdict,
+    computeComponentHealth,
   } = await import('@fragments-sdk/govern');
 
   const { scanCodebase } = await import(
@@ -123,20 +124,65 @@ export async function governScan(
     }
   }
 
-  // 3. Build adapters. Auto-add cloud if FRAGMENTS_API_KEY is set
+  // 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());
+    adapters.push(createCloudAdapter({ codeTokens, contractRegistry }));
     if (!quiet) {
       console.log(pc.dim('  Cloud audit enabled (FRAGMENTS_API_KEY detected)\n'));
     }
   }
 
-  // 4. Create engine
-  const engine = createEngine(policy, adapters);
+  // 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,
+  );
 
-  // 5. Scan codebase
+  // 6. Scan codebase
   if (!quiet) {
     console.log(pc.dim('  Scanning files...\n'));
   }
@@ -163,7 +209,7 @@ export async function governScan(
     );
   }
 
-  // 6. Collect all usages across components
+  // 7. Collect all usages across components
   const allUsages: ComponentUsage[] = [];
   for (const comp of Object.values(analysis.components)) {
     allUsages.push(...comp.usages);
@@ -176,12 +222,23 @@ export async function governScan(
     return { exitCode: 0 };
   }
 
-  // 7. Group by file and run checks
+  // 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);
@@ -191,6 +248,20 @@ export async function governScan(
       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++;
 
@@ -230,7 +301,10 @@ export async function governScan(
     }
   }
 
-  // 8. Summary
+  // 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}`);
@@ -245,6 +319,15 @@ export async function governScan(
       }
     }
 
+    // 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) {
@@ -256,9 +339,105 @@ export async function governScan(
     }
   }
 
+  // 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
 // ---------------------------------------------------------------------------

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

package/src/commands/init-cloud.ts

@@ -327,7 +327,34 @@ export async function initCloud(options: InitCloudOptions = {}): Promise<void> {
     console.log(pc.green(`  ✓ Created ${BRAND.configFile}`));
   }
 
-  // ── 6. Run first check ────────────────────────────────────────────
+  // ── 6. Push contracts if available ──────────────────────────────────
+  const fragmentsJsonPath = resolve('fragments.json');
+  if (existsSync(fragmentsJsonPath)) {
+    console.log(pc.dim('\n  Found fragments.json — pushing contracts to Cloud...'));
+    try {
+      const { pushContracts } = await import('@fragments-sdk/govern');
+      const raw = readFileSync(fragmentsJsonPath, 'utf-8');
+      const parsed = JSON.parse(raw);
+      if (parsed.fragments && Array.isArray(parsed.fragments)) {
+        const result = await pushContracts({
+          contractRegistry: JSON.stringify({ fragments: parsed.fragments }),
+          apiKey: auth.apiKey,
+          url: cloudUrl,
+        });
+        if (result.ok) {
+          console.log(pc.green(`  ✓ Pushed ${parsed.fragments.length} component contracts`));
+        } else {
+          console.log(pc.yellow(`  ⚠ Contract push failed: ${result.error}`));
+        }
+      }
+    } catch {
+      console.log(pc.yellow('  ⚠ Could not push contracts'));
+    }
+  } else {
+    console.log(pc.dim('\n  No fragments.json found — run `fragments scan` or `fragments build` to generate contracts'));
+  }
+
+  // ── 7. Run first check ────────────────────────────────────────────
   if (!options.skipCheck) {
     console.log(pc.dim('\n  Running first governance check...\n'));
     try {
@@ -346,9 +373,10 @@ export async function initCloud(options: InitCloudOptions = {}): Promise<void> {
     }
   }
 
-  // ── 7. Done ───────────────────────────────────────────────────────
+  // ── 8. Done ───────────────────────────────────────────────────────
   console.log(pc.green('\n  ✓ All set!') + ' Your project is connected to Fragments Cloud.\n');
   console.log(pc.dim(`  Dashboard: ${cloudUrl}`));
-  console.log(pc.dim('  Run checks: fragments govern check --cloud'));
-  console.log(pc.dim('  View config: fragments.config.ts\n'));
+  console.log(pc.dim('  Run checks:      fragments govern scan'));
+  console.log(pc.dim('  Push contracts:  fragments govern push-contracts'));
+  console.log(pc.dim('  View config:     fragments.config.ts\n'));
 }

package/src/commands/push-contracts.ts

@@ -0,0 +1,112 @@
+/**
+ * fragments push-contracts
+ *
+ * Push compiled component contracts to Fragments Cloud.
+ * Reads fragments.json from the project root (or builds it from .contract.json files)
+ * and posts the contract registry to the Cloud ingest endpoint.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import pc from 'picocolors';
+import { BRAND } from '../core/index.js';
+
+export interface PushContractsOptions {
+  /** Path to fragments.json or directory containing .contract.json files */
+  input?: string;
+  /** Fragments Cloud URL */
+  url?: string;
+  /** API key (defaults to FRAGMENTS_API_KEY env var) */
+  apiKey?: string;
+  /** Suppress output */
+  quiet?: boolean;
+}
+
+export async function pushContracts(
+  options: PushContractsOptions = {},
+): Promise<{ exitCode: number }> {
+  const quiet = options.quiet ?? false;
+  const apiKey = options.apiKey ?? process.env.FRAGMENTS_API_KEY;
+
+  if (!apiKey) {
+    console.error(
+      pc.red('No API key found. Set FRAGMENTS_API_KEY or pass --api-key.'),
+    );
+    return { exitCode: 1 };
+  }
+
+  if (!quiet) {
+    console.log(pc.cyan(`\n${BRAND.name} Push Contracts\n`));
+  }
+
+  // 1. Find contract registry
+  const inputPath = options.input
+    ? resolve(options.input)
+    : resolve('fragments.json');
+
+  if (!existsSync(inputPath)) {
+    console.error(
+      pc.red(`Contract registry not found at ${inputPath}`),
+    );
+    console.error(
+      pc.dim('Run `fragments build` or `fragments scan` to generate fragments.json first.'),
+    );
+    return { exitCode: 1 };
+  }
+
+  // 2. Parse and validate
+  let contractRegistry: string;
+  let componentCount = 0;
+
+  try {
+    const raw = readFileSync(inputPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    const fragments = parsed.fragments ?? parsed;
+
+    if (!Array.isArray(fragments)) {
+      console.error(pc.red('Invalid contract registry: expected fragments array'));
+      return { exitCode: 1 };
+    }
+
+    componentCount = fragments.length;
+    contractRegistry = JSON.stringify({ fragments });
+  } catch (error) {
+    console.error(
+      pc.red('Failed to parse contract registry:'),
+      error instanceof Error ? error.message : 'unknown error',
+    );
+    return { exitCode: 1 };
+  }
+
+  if (componentCount === 0) {
+    console.warn(pc.yellow('No components found in contract registry. Nothing to push.'));
+    return { exitCode: 0 };
+  }
+
+  if (!quiet) {
+    console.log(pc.dim(`  Found ${componentCount} component contracts\n`));
+    console.log(pc.dim('  Pushing to Fragments Cloud...\n'));
+  }
+
+  // 3. Push to Cloud
+  const { pushContracts: push } = await import('@fragments-sdk/govern');
+
+  const result = await push({
+    contractRegistry,
+    url: options.url,
+    apiKey,
+  });
+
+  if (!result.ok) {
+    console.error(pc.red(`Failed to push contracts: ${result.error}`));
+    return { exitCode: 1 };
+  }
+
+  if (!quiet) {
+    console.log(
+      pc.green(`  ✓ Pushed ${componentCount} component contracts to Fragments Cloud\n`),
+    );
+  }
+
+  return { exitCode: 0 };
+}

package/src/commands/scan-generate.ts

@@ -27,7 +27,7 @@ import {
   type ComponentMeta,
   type PropMeta,
   type CompositionMeta,
-} from "../core/component-extractor.js";
+} from '@fragments-sdk/extract';
 
 // ---------------------------------------------------------------------------
 // Types

package/src/commands/scan.ts

@@ -22,6 +22,7 @@ import {
 import {
   loadConfig,
   discoverAllComponents,
+  findConfigFile,
   type DiscoveredComponent,
 } from "../core/node.js";
 import {
@@ -38,6 +39,7 @@ import {
   type PropsExtractionResult,
   type ParsedStoryFile,
 } from "../service/index.js";
+import { getGeneratorVersion } from '@fragments-sdk/compiler';
 
 export interface ScanOptions {
   /** Path to config file */
@@ -271,10 +273,21 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
   // Write output
   const outputPath = resolve(configDir, outputFile);
   await mkdir(dirname(outputPath), { recursive: true });
+  const generatorVersion = await getGeneratorVersion();
+  const buildInputs = components
+    .map((component) => relative(configDir, component.sourcePath).split("\\").join("/"))
+    .sort();
+  const configPath = options.config ? resolve(process.cwd(), options.config) : findConfigFile(configDir);
+  if (configPath) {
+    buildInputs.push(relative(configDir, configPath).split("\\").join("/"));
+    buildInputs.sort();
+  }
 
   const output: CompiledFragmentsFile = {
     version: "1.0.0",
     generatedAt: new Date().toISOString(),
+    generatorVersion,
+    buildInputs,
     fragments,
   };
 

package/src/commands/sync.ts

@@ -13,8 +13,8 @@ import { BRAND } from '../core/index.js';
 import { loadConfig } from '../core/node.js';
 import { discoverFragmentFiles, loadFragmentFile } from '../core/node.js';
 import { parseFragmentFile } from '../core/parser.js';
-import { resolveComponentSourcePath } from '../core/auto-props.js';
-import { createComponentExtractor, type PropMeta, type CompositionMeta } from '../core/component-extractor.js';
+import { resolveComponentSourcePath } from '@fragments-sdk/extract';
+import { createComponentExtractor, type PropMeta, type CompositionMeta } from '@fragments-sdk/extract';
 import type { FragmentsConfig } from '@fragments-sdk/core';
 
 // ---------------------------------------------------------------------------