@fragments-sdk/cli 0.14.3 → 0.15.1

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/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) {

package/src/commands/inspect.ts

@@ -0,0 +1,290 @@
+/**
+ * `fragments inspect` — inspect a single component from fragments.json.
+ *
+ * Loads the compiled output, finds the named component, and prints
+ * a human-readable summary or JSON depending on flags. Supports field
+ * filtering (dot notation), variant filtering, and verbosity levels.
+ */
+
+import pc from 'picocolors';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type { CompiledFragmentsFile } from '../core/index.js';
+import { BRAND } from '../core/index.js';
+import { loadConfig } from '../core/node.js';
+import { projectFields } from '../shared/project-fields.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface InspectCommandOptions {
+  config?: string;
+  fields?: string;
+  variant?: string;
+  verbosity?: 'compact' | 'standard' | 'full';
+  maxExamples?: number;
+  json?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Simple Levenshtein distance for "did you mean?" suggestions.
+ */
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  const dp: number[][] = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0) as number[]);
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1]
+        ? dp[i - 1][j - 1]
+        : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+
+function findClosestMatch(input: string, candidates: string[], maxDistance = 3): string | null {
+  const inputLower = input.toLowerCase();
+  let bestMatch: string | null = null;
+  let bestDist = maxDistance + 1;
+
+  for (const candidate of candidates) {
+    const dist = levenshtein(inputLower, candidate.toLowerCase());
+    if (dist < bestDist) {
+      bestDist = dist;
+      bestMatch = candidate;
+    } else if (dist === bestDist && bestMatch) {
+      if (Math.abs(candidate.length - input.length) < Math.abs(bestMatch.length - input.length)) {
+        bestMatch = candidate;
+      }
+    }
+  }
+
+  return bestDist <= maxDistance ? bestMatch : null;
+}
+
+// ---------------------------------------------------------------------------
+// Command implementation
+// ---------------------------------------------------------------------------
+
+export async function inspect(
+  component: string,
+  options: InspectCommandOptions,
+): Promise<void> {
+  const { config, configDir } = await loadConfig(options.config);
+  const outputPath = resolve(configDir, config.outFile ?? BRAND.outFile);
+
+  let data: CompiledFragmentsFile;
+  try {
+    const content = await readFile(outputPath, 'utf-8');
+    data = JSON.parse(content) as CompiledFragmentsFile;
+  } catch {
+    console.error(
+      pc.red(`Error: Could not load ${BRAND.outFile}. Run \`${BRAND.cliCommand} build\` first.`),
+    );
+    process.exit(1);
+  }
+
+  // Find fragment (case-insensitive)
+  const fragment = Object.values(data.fragments).find(
+    (s) => s.meta.name.toLowerCase() === component.toLowerCase(),
+  );
+
+  if (!fragment) {
+    const allNames = Object.values(data.fragments).map((s) => s.meta.name);
+    const closest = findClosestMatch(component, allNames);
+    const suggestion = closest
+      ? ` Did you mean "${closest}"?`
+      : '';
+    console.error(
+      pc.red(`Error: Component "${component}" not found.${suggestion}`),
+    );
+    console.error(
+      pc.dim(`Use \`${BRAND.cliCommand} discover\` to see available components.`),
+    );
+    process.exit(1);
+  }
+
+  const verbosity = options.verbosity ?? 'standard';
+
+  // --- Variant filtering ---
+  let variants = fragment.variants;
+  if (options.variant) {
+    const query = options.variant.toLowerCase();
+    let filtered = variants.filter((v) => v.name.toLowerCase() === query);
+    if (filtered.length === 0) {
+      filtered = variants.filter((v) => v.name.toLowerCase().startsWith(query));
+    }
+    if (filtered.length === 0) {
+      filtered = variants.filter((v) => v.name.toLowerCase().includes(query));
+    }
+    if (filtered.length > 0) {
+      variants = filtered;
+    } else {
+      console.error(
+        pc.red(
+          `Error: Variant "${options.variant}" not found for ${component}. ` +
+          `Available: ${fragment.variants.map((v) => v.name).join(', ')}`,
+        ),
+      );
+      process.exit(1);
+    }
+  }
+  if (options.maxExamples && options.maxExamples > 0) {
+    variants = variants.slice(0, options.maxExamples);
+  }
+
+  // --- Build full result ---
+  const propsReference = Object.entries(fragment.props ?? {}).map(([propName, prop]) => ({
+    name: propName,
+    type: prop.type,
+    required: prop.required,
+    default: prop.default,
+    description: prop.description,
+  }));
+
+  const propConstraints = Object.entries(fragment.props ?? {})
+    .filter(([, prop]) => prop.constraints && prop.constraints.length > 0)
+    .map(([pName, prop]) => ({
+      prop: pName,
+      constraints: prop.constraints,
+    }));
+
+  const examples = variants.map((variant) => ({
+    variant: variant.name,
+    description: variant.description,
+    code: variant.code ?? `<${fragment.meta.name} />`,
+  }));
+
+  const fullResult = {
+    meta: fragment.meta,
+    props: fragment.props,
+    variants: fragment.variants,
+    relations: fragment.relations,
+    contract: fragment.contract,
+    generated: fragment._generated,
+    guidelines: {
+      when: fragment.usage?.when ?? [],
+      whenNot: fragment.usage?.whenNot ?? [],
+      guidelines: fragment.usage?.guidelines ?? [],
+      accessibility: fragment.usage?.accessibility ?? [],
+      propConstraints,
+      alternatives: fragment.relations
+        ?.filter((r) => r.relationship === 'alternative')
+        .map((r) => ({ component: r.component, note: r.note })) ?? [],
+    },
+    examples: {
+      import: `import { ${fragment.meta.name} } from '${data.packageName ?? BRAND.nameLower}';`,
+      code: examples,
+      propsReference,
+    },
+  };
+
+  // --- Apply verbosity + field filtering ---
+  const fieldsArray = options.fields
+    ? options.fields.split(',').map((f) => f.trim())
+    : undefined;
+
+  // Alias legacy field paths
+  const aliasMap: Record<string, string> = { usage: 'guidelines' };
+  const resolvedFields = fieldsArray?.map((f) => {
+    const parts = f.split('.');
+    if (aliasMap[parts[0]]) parts[0] = aliasMap[parts[0]];
+    return parts.join('.');
+  });
+
+  let result: unknown;
+  if (verbosity === 'compact' && !resolvedFields?.length) {
+    result = {
+      meta: fullResult.meta,
+      propNames: Object.keys(fragment.props ?? {}),
+      variantNames: fragment.variants.map((v) => v.name),
+    };
+  } else {
+    result = resolvedFields && resolvedFields.length > 0
+      ? projectFields(fullResult as unknown as Record<string, unknown>, resolvedFields)
+      : fullResult;
+  }
+
+  // --- Output ---
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  // Human-readable output
+  const meta = fragment.meta;
+  console.log(pc.bold(`\n${meta.name}\n`));
+  console.log(`  ${pc.cyan('Category:')}    ${meta.category}`);
+  console.log(`  ${pc.cyan('Status:')}      ${meta.status ?? 'stable'}`);
+  if (meta.description) {
+    console.log(`  ${pc.cyan('Description:')} ${meta.description}`);
+  }
+  if (meta.tags && meta.tags.length > 0) {
+    console.log(`  ${pc.cyan('Tags:')}        ${meta.tags.join(', ')}`);
+  }
+
+  // Props table
+  const propEntries = Object.entries(fragment.props ?? {});
+  if (propEntries.length > 0) {
+    console.log(pc.bold('\n  Props\n'));
+    console.log(
+      pc.dim(
+        `  ${'Name'.padEnd(24)} ${'Type'.padEnd(20)} ${'Required'.padEnd(10)} ${'Default'}`,
+      ),
+    );
+    console.log(pc.dim(`  ${'─'.repeat(70)}`));
+
+    const displayProps = verbosity === 'compact' ? propEntries.slice(0, 5) : propEntries;
+    for (const [name, prop] of displayProps) {
+      const propName = name.length > 22 ? name.slice(0, 19) + '...' : name;
+      const propType = (prop.type ?? '').length > 18
+        ? (prop.type ?? '').slice(0, 15) + '...'
+        : (prop.type ?? '');
+      console.log(
+        `  ${pc.cyan(propName.padEnd(24))} ${propType.padEnd(20)} ${(prop.required ? 'yes' : 'no').padEnd(10)} ${pc.dim(String(prop.default ?? '-'))}`,
+      );
+    }
+    if (verbosity === 'compact' && propEntries.length > 5) {
+      console.log(pc.dim(`  ... and ${propEntries.length - 5} more`));
+    }
+  }
+
+  // Variants list
+  if (variants.length > 0) {
+    console.log(pc.bold('\n  Variants\n'));
+    for (const v of variants) {
+      console.log(`  ${pc.yellow(v.name)}${v.description ? pc.dim(` — ${v.description}`) : ''}`);
+    }
+  }
+
+  // Usage guidelines (standard/full only)
+  if (verbosity !== 'compact') {
+    const when = fragment.usage?.when ?? [];
+    const whenNot = fragment.usage?.whenNot ?? [];
+    if (when.length > 0 || whenNot.length > 0) {
+      console.log(pc.bold('\n  Usage Guidelines\n'));
+      if (when.length > 0) {
+        console.log(`  ${pc.green('When to use:')}`);
+        for (const w of when) {
+          console.log(`    ${pc.dim('•')} ${w}`);
+        }
+      }
+      if (whenNot.length > 0) {
+        console.log(`  ${pc.red('When NOT to use:')}`);
+        for (const w of whenNot) {
+          console.log(`    ${pc.dim('•')} ${w}`);
+        }
+      }
+    }
+  }
+
+  console.log();
+}

package/src/commands/migrate-contract.ts

@@ -0,0 +1,85 @@
+/**
+ * CLI command: fragments migrate-contract
+ *
+ * Converts .fragment.tsx files to .contract.json format.
+ */
+
+import pc from 'picocolors';
+import fg from 'fast-glob';
+import { resolve } from 'node:path';
+import { loadConfig } from '../core/node.js';
+import { migrateFragmentToContract } from '../migrate/fragment-to-contract.js';
+
+export interface MigrateContractOptions {
+  config?: string;
+  glob?: string;
+  dryRun?: boolean;
+  tsconfig?: string;
+}
+
+export async function migrateContract(options: MigrateContractOptions): Promise<{
+  migrated: number;
+  failed: number;
+  warnings: number;
+}> {
+  const { config, configDir } = await loadConfig(options.config);
+  const pattern = options.glob ?? 'src/**/*.fragment.tsx';
+
+  console.log(pc.blue(`Migrating fragment files matching: ${pattern}`));
+  if (options.dryRun) {
+    console.log(pc.yellow('(dry run — no files will be written)'));
+  }
+
+  const files = await fg(pattern, { cwd: configDir, absolute: true });
+
+  if (files.length === 0) {
+    console.log(pc.yellow('No fragment files found matching pattern.'));
+    return { migrated: 0, failed: 0, warnings: 0 };
+  }
+
+  console.log(pc.dim(`Found ${files.length} fragment file(s)`));
+
+  let migrated = 0;
+  let failed = 0;
+  let totalWarnings = 0;
+
+  // Find tsconfig
+  const tsconfigPath = options.tsconfig
+    ? resolve(options.tsconfig)
+    : undefined;
+
+  for (const file of files) {
+    try {
+      const result = await migrateFragmentToContract(file, configDir, {
+        dryRun: options.dryRun,
+        tsconfigPath,
+      });
+
+      migrated++;
+      const verb = options.dryRun ? 'Would migrate' : 'Migrated';
+      console.log(pc.green(`  ✓ ${verb}: ${result.contractPath}`));
+
+      if (result.warnings.length > 0) {
+        totalWarnings += result.warnings.length;
+        for (const w of result.warnings) {
+          console.log(pc.yellow(`    ⚠ ${w}`));
+        }
+      }
+    } catch (error) {
+      failed++;
+      console.log(pc.red(`  ✗ Failed: ${file}`));
+      console.log(pc.dim(`    ${error instanceof Error ? error.message : String(error)}`));
+    }
+  }
+
+  console.log('');
+  console.log(pc.bold('Migration summary:'));
+  console.log(`  ${pc.green(`${migrated} migrated`)}  ${pc.red(`${failed} failed`)}  ${pc.yellow(`${totalWarnings} warnings`)}`);
+
+  if (!options.dryRun && migrated > 0) {
+    console.log('');
+    console.log(pc.dim('Run `fragments build` to verify migrated contracts compile correctly.'));
+  }
+
+  return { migrated, failed, warnings: totalWarnings };
+}