@fragments-sdk/cli 0.11.1 → 0.13.0

package/src/ai-client.ts

@@ -0,0 +1,156 @@
+/**
+ * Shared AI client infrastructure for LLM-powered CLI commands.
+ *
+ * Used by:
+ * - `fragments enhance` (usage analysis + documentation generation)
+ * - `fragments init --scan --enrich` (knowledge field enrichment)
+ *
+ * Supports Anthropic (Claude) and OpenAI APIs via dynamic import.
+ * No new dependencies — uses existing @anthropic-ai/sdk and openai.
+ */
+
+export type AIProvider = 'anthropic' | 'openai' | 'none';
+
+/**
+ * Default lightweight models for enrichment (cheap, fast).
+ * Enhance uses its own heavier models locally.
+ */
+export const ENRICHMENT_MODELS: Record<AIProvider, string> = {
+  anthropic: 'claude-haiku-4-5-20251001',
+  openai: 'gpt-4o-mini',
+  none: '',
+};
+
+/**
+ * Detect which AI provider to use based on available API keys and options.
+ */
+export function detectProvider(opts?: {
+  provider?: AIProvider;
+  apiKey?: string;
+}): AIProvider {
+  if (opts?.provider) return opts.provider;
+  if (opts?.apiKey) {
+    if (opts.apiKey.startsWith('sk-ant-')) return 'anthropic';
+    if (opts.apiKey.startsWith('sk-')) return 'openai';
+  }
+  if (process.env.ANTHROPIC_API_KEY) return 'anthropic';
+  if (process.env.OPENAI_API_KEY) return 'openai';
+  return 'none';
+}
+
+/**
+ * Resolve the API key for a given provider.
+ */
+export function getApiKey(provider: AIProvider, explicitKey?: string): string | undefined {
+  if (explicitKey) return explicitKey;
+  if (provider === 'anthropic') return process.env.ANTHROPIC_API_KEY;
+  if (provider === 'openai') return process.env.OPENAI_API_KEY;
+  return undefined;
+}
+
+/**
+ * Create an AI client for the given provider via dynamic import.
+ */
+export async function createAIClient(provider: AIProvider, apiKey: string): Promise<unknown> {
+  if (provider === 'anthropic') {
+    const Anthropic = (await import('@anthropic-ai/sdk')).default;
+    return new Anthropic({ apiKey });
+  }
+  if (provider === 'openai') {
+    const OpenAI = (await import('openai')).default;
+    return new OpenAI({ apiKey });
+  }
+  throw new Error(`Unknown provider: ${provider}`);
+}
+
+export interface CompletionResult {
+  text: string;
+  inputTokens: number;
+  outputTokens: number;
+}
+
+/**
+ * Generate a completion using the appropriate provider API.
+ */
+export async function generateCompletion(
+  client: unknown,
+  provider: AIProvider,
+  model: string,
+  system: string,
+  user: string,
+  maxTokens: number = 1024
+): Promise<CompletionResult> {
+  if (provider === 'anthropic') {
+    const anthropic = client as import('@anthropic-ai/sdk').default;
+    const response = await anthropic.messages.create({
+      model,
+      max_tokens: maxTokens,
+      system,
+      messages: [{ role: 'user', content: user }],
+    });
+
+    const content = response.content[0];
+    if (content.type !== 'text') {
+      throw new Error('Unexpected response type');
+    }
+
+    return {
+      text: content.text,
+      inputTokens: response.usage?.input_tokens || 0,
+      outputTokens: response.usage?.output_tokens || 0,
+    };
+  }
+
+  if (provider === 'openai') {
+    const openai = client as import('openai').default;
+    const response = await openai.chat.completions.create({
+      model,
+      max_tokens: maxTokens,
+      messages: [
+        { role: 'system', content: system },
+        { role: 'user', content: user },
+      ],
+    });
+
+    const content = response.choices[0]?.message?.content;
+    if (!content) {
+      throw new Error('No response from OpenAI');
+    }
+
+    return {
+      text: content,
+      inputTokens: response.usage?.prompt_tokens || 0,
+      outputTokens: response.usage?.completion_tokens || 0,
+    };
+  }
+
+  throw new Error(`Unknown provider: ${provider}`);
+}
+
+/**
+ * Parse a JSON response from an LLM, handling ```json fences and raw JSON.
+ */
+export function parseJSONResponse<T = unknown>(text: string): T {
+  const jsonMatch = text.match(/```json\n?([\s\S]*?)\n?```/) || text.match(/\{[\s\S]*\}/);
+  const jsonStr = jsonMatch ? (jsonMatch[1] || jsonMatch[0]) : text;
+  return JSON.parse(jsonStr);
+}
+
+/**
+ * Calculate estimated cost based on model and token usage.
+ */
+export function calculateCost(model: string, inputTokens: number, outputTokens: number): number {
+  // Approximate costs per 1M tokens (input/output)
+  const pricing: Record<string, { input: number; output: number }> = {
+    // Anthropic
+    'claude-haiku-4-5-20251001': { input: 0.80, output: 4.00 },
+    'claude-sonnet-4-20250514': { input: 3.00, output: 15.00 },
+    // OpenAI
+    'gpt-4o-mini': { input: 0.15, output: 0.60 },
+    'gpt-4o': { input: 2.50, output: 10.00 },
+  };
+
+  const modelPricing = pricing[model] || { input: 3.00, output: 15.00 };
+  return (inputTokens / 1_000_000) * modelPricing.input +
+         (outputTokens / 1_000_000) * modelPricing.output;
+}

package/src/bin.ts

@@ -39,6 +39,8 @@ import { graph } from './commands/graph.js';
 import { perf } from './commands/perf.js';
 import { doctor } from './commands/doctor.js';
 import { setup } from './commands/setup.js';
+import { sync } from './commands/sync.js';
+import { governCheck, governInit, governReport } from './commands/govern.js';
 
 // Import existing commands that were already extracted
 import { runScreenshotCommand } from './screenshot.js';
@@ -62,6 +64,8 @@ program
   .option('--schema', 'Validate fragment schema only')
   .option('--coverage', 'Validate coverage only')
   .option('--snippets', 'Validate snippet/render policy only')
+  .option('--drift', 'Detect metadata drift between source and fragments')
+  .option('--tsconfig <path>', 'Path to tsconfig.json (for drift detection)')
   .option('--snippet-mode <mode>', 'Override snippet policy mode (warn|error)')
   .option('--component-start <name>', 'Start component name for alphabetical snippet batch validation')
   .option('--component-limit <n>', 'Component count for alphabetical snippet batch validation', (value) => Number.parseInt(value, 10))
@@ -77,6 +81,33 @@ program
     }
   });
 
+// ============================================================================
+// SYNC COMMAND
+// ============================================================================
+program
+  .command('sync')
+  .description('Auto-update fragment files from component source')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--tsconfig <path>', 'Path to tsconfig.json')
+  .option('--dry-run', 'Preview changes without writing')
+  .option('--component <name>', 'Sync specific component only')
+  .action(async (options) => {
+    try {
+      const result = await sync({
+        config: options.config,
+        tsconfig: options.tsconfig,
+        dryRun: options.dryRun,
+        component: options.component,
+      });
+      if (!result.success) {
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
 // ============================================================================
 // BUILD COMMAND
 // ============================================================================
@@ -794,10 +825,16 @@ program
 // ============================================================================
 program
   .command('init')
-  .description('Initialize fragments in a project (interactive by default)')
+  .description('Initialize fragments in a project (zero-config by default)')
   .option('--force', 'Overwrite existing config')
-  .option('-y, --yes', 'Non-interactive mode - auto-detect and use defaults')
+  .option('-y, --yes', 'Non-interactive mode (now the default)')
+  .option('--configure', 'Interactive mode for theme seeds, snapshots, etc.')
   .option('--scan <path>', 'Scan a TypeScript component directory and generate fragment files')
+  .option('--enrich', 'Use AI to fill knowledge fields during --scan (requires API key)')
+  .option('--dry-run', 'Show what --enrich would generate without calling API')
+  .option('--provider <provider>', 'AI provider for enrichment: anthropic or openai')
+  .option('--api-key <key>', 'API key for AI enrichment')
+  .option('--model <model>', 'Override AI model for enrichment')
   .action(async (options) => {
     try {
       const { init } = await import('./commands/init.js');
@@ -806,6 +843,12 @@ program
         force: options.force,
         yes: options.scan ? true : options.yes,
         scan: options.scan,
+        configure: options.configure,
+        enrich: options.enrich,
+        dryRun: options.dryRun,
+        provider: options.provider,
+        apiKey: options.apiKey,
+        model: options.model,
       });
 
       if (!result.success) {
@@ -1073,5 +1116,59 @@ program
     }
   });
 
+// ============================================================================
+// GOVERN COMMAND
+// ============================================================================
+const governCmd = program
+  .command('govern')
+  .description('AI UI governance checks');
+
+governCmd
+  .command('check')
+  .description('Validate a UISpec against governance policies')
+  .option('-i, --input <path>', 'Path to UISpec JSON file (or - for stdin)')
+  .option('-c, --config <path>', 'Path to govern.config.ts')
+  .option('-f, --format <format>', 'Output format: summary, json, sarif', 'summary')
+  .option('-q, --quiet', 'Suppress non-error output')
+  .action(async (options) => {
+    try {
+      const { exitCode } = await governCheck({
+        input: options.input,
+        config: options.config,
+        format: options.format,
+        quiet: options.quiet,
+      });
+      process.exit(exitCode);
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+governCmd
+  .command('init')
+  .description('Generate a govern.config.ts template')
+  .option('-o, --output <path>', 'Output path', 'govern.config.ts')
+  .action(async (options) => {
+    try {
+      await governInit({ output: options.output });
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+governCmd
+  .command('report')
+  .description('Summarize governance audit log')
+  .action(async () => {
+    try {
+      await governReport();
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
 // Parse command line arguments
 program.parse();

package/src/build.ts

@@ -21,10 +21,13 @@ import {
   generateContextMd,
 } from "./core/node.js";
 import {
-  extractCustomPropsFromComponentFile,
   resolveComponentSourcePath,
-  type AutoDetectedPropDefinition,
 } from "./core/auto-props.js";
+import {
+  createComponentExtractor,
+  type PropMeta,
+  type ComponentMeta,
+} from "./core/component-extractor.js";
 import { buildComponentGraph } from "./core/graph-extractor.js";
 import { serializeGraph } from "@fragments-sdk/context/graph";
 import { resolvePerformanceConfig } from "./core/index.js";
@@ -53,17 +56,21 @@ function normalizeParsedProps(
 
 function mergeDocumentedAndAutoProps(
   documentedProps: Record<string, CompiledProp>,
-  autoProps: Record<string, AutoDetectedPropDefinition>
+  autoProps: Record<string, PropMeta>
 ): Record<string, CompiledProp> {
   return Object.fromEntries(
-    Object.keys(autoProps).map((name) => {
+    Object.keys(autoProps)
+      // Strip inherited HTML/React props — they're identical across all components
+      // and bloat fragments.json. MCP consumers know these exist implicitly.
+      .filter((name) => autoProps[name].source === 'local' || name in documentedProps)
+      .map((name) => {
       const documented = documentedProps[name];
       const auto = autoProps[name];
 
       return [
         name,
         {
-          type: auto.type,
+          type: auto.typeKind,
           description: documented?.description ?? auto.description ?? "",
           default: auto.default !== undefined ? auto.default : documented?.default,
           required: auto.required,
@@ -75,6 +82,30 @@ function mergeDocumentedAndAutoProps(
   );
 }
 
+/**
+ * Auto-compile a propsSummary for the contract from extracted props.
+ * Format: "variant: primary|secondary|ghost (required)"
+ */
+function compilePropsSummary(props: Record<string, PropMeta>): string[] {
+  return Object.entries(props)
+    .filter(([_, p]) => p.source === 'local')
+    .map(([name, prop]) => {
+      let summary = name + ': ';
+      if (prop.values && prop.values.length > 0) {
+        summary += prop.values.join('|');
+      } else {
+        summary += prop.typeKind;
+      }
+      if (prop.default !== undefined) {
+        summary += ` (default: ${prop.default})`;
+      }
+      if (prop.required) {
+        summary += ' (required)';
+      }
+      return summary;
+    });
+}
+
 export interface BuildResult {
   success: boolean;
   outputPath: string;
@@ -98,6 +129,15 @@ export async function buildFragments(
   const warnings: Array<{ file: string; warning: string }> = [];
   const fragments: CompiledFragmentsFile["fragments"] = {};
 
+  // Create a persistent extractor — shared LanguageService across all fragments
+  // Try to find a tsconfig.json in the config directory
+  const tsconfigCandidates = [
+    resolve(configDir, 'tsconfig.json'),
+    resolve(configDir, '..', 'tsconfig.json'),
+  ];
+  const tsconfigPath = tsconfigCandidates.find((p) => existsSync(p));
+  const extractor = createComponentExtractor(tsconfigPath);
+
   for (const file of files) {
     try {
       // Read file content as text
@@ -139,38 +179,38 @@ export async function buildFragments(
         parsed.componentImport
       );
 
+      // Extract full component metadata using persistent LanguageService
+      let extractedMeta: ComponentMeta | null = null;
       if (componentExportName && componentSourcePath) {
-        const autoPropsResult = extractCustomPropsFromComponentFile(
-          componentSourcePath,
-          componentExportName
-        );
-
-        for (const warning of autoPropsResult.warnings) {
-          warnings.push({ file: file.relativePath, warning });
+        try {
+          extractedMeta = extractor.extract(componentSourcePath, componentExportName);
+        } catch {
+          // Extraction failure is non-fatal — fall back to documented props
         }
 
-        const hasAutoProps = Object.keys(autoPropsResult.props).length > 0;
-        if (autoPropsResult.resolved && hasAutoProps) {
-          const removedDocumentedProps = Object.keys(documentedProps).filter(
-            (propName) => !(propName in autoPropsResult.props)
-          );
+        if (extractedMeta) {
+          const autoProps = extractedMeta.props;
+          const hasAutoProps = Object.keys(autoProps).length > 0;
 
-          if (removedDocumentedProps.length > 0) {
+          if (hasAutoProps) {
+            const removedDocumentedProps = Object.keys(documentedProps).filter(
+              (propName) => !(propName in autoProps)
+            );
+
+            if (removedDocumentedProps.length > 0) {
+              warnings.push({
+                file: file.relativePath,
+                warning: `Removed ${removedDocumentedProps.length} documented props not present in source API: ${removedDocumentedProps.join(", ")}`,
+              });
+            }
+
+            mergedProps = mergeDocumentedAndAutoProps(documentedProps, autoProps);
+          } else if (Object.keys(documentedProps).length > 0) {
             warnings.push({
               file: file.relativePath,
-              warning: `Removed ${removedDocumentedProps.length} documented props not present in source API: ${removedDocumentedProps.join(", ")}`,
+              warning: "Auto-props extraction returned no props; falling back to documented props",
             });
           }
-
-          mergedProps = mergeDocumentedAndAutoProps(
-            documentedProps,
-            autoPropsResult.props
-          );
-        } else if (autoPropsResult.resolved && !hasAutoProps && Object.keys(documentedProps).length > 0) {
-          warnings.push({
-            file: file.relativePath,
-            warning: "Auto-props extraction returned no custom props; falling back to documented props",
-          });
         }
       } else if (!componentExportName) {
         warnings.push({
@@ -184,6 +224,26 @@ export async function buildFragments(
         });
       }
 
+      // Auto-compile contract if not manually authored
+      let contract = parsed.contract;
+      if (!contract?.propsSummary && extractedMeta) {
+        const summary = compilePropsSummary(extractedMeta.props);
+        if (summary.length > 0) {
+          contract = { ...contract, propsSummary: summary };
+        }
+      }
+
+      // Auto-enrich AI metadata from extractor's composition data
+      let ai = parsed.ai;
+      if (extractedMeta?.composition) {
+        const comp = extractedMeta.composition;
+        ai = {
+          compositionPattern: comp.pattern,
+          subComponents: comp.parts.map((p) => p.name),
+          ...ai, // Manually authored ai fields take precedence
+        };
+      }
+
       // Build compiled fragment from parsed metadata
       const compiled: CompiledFragment = {
         filePath: file.relativePath,
@@ -221,10 +281,10 @@ export async function buildFragments(
           ...(v.figma && { figma: v.figma }),
           ...(v.args && { args: v.args }),
         })),
-        // Include AI metadata if present
-        ...(parsed.ai && { ai: parsed.ai }),
-        // Include contract metadata if present
-        ...(parsed.contract && { contract: parsed.contract }),
+        // Include AI metadata (auto-enriched or manual)
+        ...(ai && { ai }),
+        // Include contract metadata (auto-compiled or manual)
+        ...(contract && { contract }),
       };
 
       fragments[parsed.meta.name] = compiled;
@@ -236,6 +296,8 @@ export async function buildFragments(
     }
   }
 
+  extractor.dispose();
+
   // Discover and compile block files
   const blocks: Record<string, CompiledBlock> = {};
   try {