@fragments-sdk/cli 0.14.3 → 0.15.0

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 };
+}