@fragments-sdk/cli 0.2.2

package/src/core/composition.ts

@@ -0,0 +1,255 @@
+import type { CompiledSegment, RelationshipType } from "./types.js";
+
+// --- Public types ---
+
+export interface CompositionWarning {
+  type:
+    | "missing_parent"
+    | "missing_child"
+    | "missing_composition"
+    | "redundant_alternative"
+    | "deprecated"
+    | "experimental";
+  component: string;
+  message: string;
+  relatedComponent?: string;
+}
+
+export interface CompositionSuggestion {
+  component: string;
+  reason: string;
+  relationship: RelationshipType | "category_gap";
+  sourceComponent: string;
+}
+
+export interface CompositionGuideline {
+  component: string;
+  guideline: string;
+}
+
+export interface CompositionAnalysis {
+  /** The validated component names (filtered to those that exist) */
+  components: string[];
+
+  /** Components requested but not found in the registry */
+  unknown: string[];
+
+  /** Issues with the current selection */
+  warnings: CompositionWarning[];
+
+  /** Components to consider adding */
+  suggestions: CompositionSuggestion[];
+
+  /** Relevant usage guidelines for the selected components */
+  guidelines: CompositionGuideline[];
+}
+
+// --- Category affinities ---
+
+const CATEGORY_AFFINITIES: Record<string, string[]> = {
+  forms: ["feedback"],
+  actions: ["feedback"],
+};
+
+// --- Main function ---
+
+/**
+ * Analyzes a set of components as a composition group.
+ * Returns warnings about missing relations, usage conflicts,
+ * and suggestions for additional components.
+ *
+ * Browser-safe: no Node.js APIs used.
+ */
+export function analyzeComposition(
+  segments: Record<string, CompiledSegment>,
+  componentNames: string[],
+  _context?: string
+): CompositionAnalysis {
+  const allNames = new Set(Object.keys(segments));
+
+  // 1. Validate names
+  const components: string[] = [];
+  const unknown: string[] = [];
+  for (const name of componentNames) {
+    if (allNames.has(name)) {
+      components.push(name);
+    } else {
+      unknown.push(name);
+    }
+  }
+
+  const selectedSet = new Set(components);
+  const warnings: CompositionWarning[] = [];
+  const suggestions: CompositionSuggestion[] = [];
+  const guidelines: CompositionGuideline[] = [];
+
+  // Track suggestions to avoid duplicates
+  const suggestedSet = new Set<string>();
+
+  for (const name of components) {
+    const segment = segments[name];
+
+    // 2. Relation checks
+    if (segment.relations) {
+      for (const rel of segment.relations) {
+        switch (rel.relationship) {
+          case "parent":
+            if (!selectedSet.has(rel.component)) {
+              warnings.push({
+                type: "missing_parent",
+                component: name,
+                message: `"${name}" expects to be wrapped by "${rel.component}"${rel.note ? `: ${rel.note}` : ""}`,
+                relatedComponent: rel.component,
+              });
+            }
+            break;
+
+          case "child":
+            if (!selectedSet.has(rel.component) && !suggestedSet.has(rel.component)) {
+              suggestions.push({
+                component: rel.component,
+                reason: `"${name}" typically contains "${rel.component}"${rel.note ? `: ${rel.note}` : ""}`,
+                relationship: "child",
+                sourceComponent: name,
+              });
+              suggestedSet.add(rel.component);
+            }
+            break;
+
+          case "composition":
+            if (!selectedSet.has(rel.component)) {
+              warnings.push({
+                type: "missing_composition",
+                component: name,
+                message: `"${name}" is typically used together with "${rel.component}"${rel.note ? `: ${rel.note}` : ""}`,
+                relatedComponent: rel.component,
+              });
+            }
+            break;
+
+          case "sibling":
+            if (!selectedSet.has(rel.component) && !suggestedSet.has(rel.component)) {
+              suggestions.push({
+                component: rel.component,
+                reason: `"${rel.component}" is a sibling of "${name}"${rel.note ? `: ${rel.note}` : ""}`,
+                relationship: "sibling",
+                sourceComponent: name,
+              });
+              suggestedSet.add(rel.component);
+            }
+            break;
+
+          case "alternative":
+            if (selectedSet.has(rel.component)) {
+              warnings.push({
+                type: "redundant_alternative",
+                component: name,
+                message: `"${name}" and "${rel.component}" are alternatives — using both may be redundant${rel.note ? `: ${rel.note}` : ""}`,
+                relatedComponent: rel.component,
+              });
+            }
+            break;
+        }
+      }
+    }
+
+    // 3. Usage conflict checks (whenNot)
+    if (segment.usage?.whenNot) {
+      for (const whenNotEntry of segment.usage.whenNot) {
+        const lower = whenNotEntry.toLowerCase();
+        for (const other of components) {
+          if (other !== name && lower.includes(other.toLowerCase())) {
+            guidelines.push({
+              component: name,
+              guideline: `Potential conflict with "${other}": ${whenNotEntry}`,
+            });
+          }
+        }
+      }
+    }
+
+    // 4. Status warnings
+    if (segment.meta.status === "deprecated") {
+      warnings.push({
+        type: "deprecated",
+        component: name,
+        message: segment.meta.description
+          ? `"${name}" is deprecated: ${segment.meta.description}`
+          : `"${name}" is deprecated`,
+      });
+    } else if (segment.meta.status === "experimental") {
+      warnings.push({
+        type: "experimental",
+        component: name,
+        message: `"${name}" is experimental and may change without notice`,
+      });
+    }
+  }
+
+  // 5. Category gap analysis
+  const selectedCategories = new Set(
+    components.map((name) => segments[name].meta.category)
+  );
+
+  for (const [category, affinities] of Object.entries(CATEGORY_AFFINITIES)) {
+    if (!selectedCategories.has(category)) continue;
+
+    for (const neededCategory of affinities) {
+      if (selectedCategories.has(neededCategory)) continue;
+
+      // Find the best component from the needed category
+      const candidate = findBestCategoryCandidate(
+        segments,
+        neededCategory,
+        selectedSet,
+        suggestedSet
+      );
+      if (candidate) {
+        suggestions.push({
+          component: candidate,
+          reason: `Compositions using "${category}" components often benefit from a "${neededCategory}" component`,
+          relationship: "category_gap",
+          sourceComponent: components.find(
+            (n) => segments[n].meta.category === category
+          )!,
+        });
+        suggestedSet.add(candidate);
+      }
+    }
+  }
+
+  return { components, unknown, warnings, suggestions, guidelines };
+}
+
+/**
+ * Find the best candidate component from a given category.
+ * Prefers stable components and avoids already-selected or already-suggested ones.
+ */
+function findBestCategoryCandidate(
+  segments: Record<string, CompiledSegment>,
+  category: string,
+  selectedSet: Set<string>,
+  suggestedSet: Set<string>
+): string | null {
+  let best: string | null = null;
+  let bestScore = -1;
+
+  for (const [name, segment] of Object.entries(segments)) {
+    if (segment.meta.category !== category) continue;
+    if (selectedSet.has(name) || suggestedSet.has(name)) continue;
+
+    const status = segment.meta.status ?? "stable";
+    let score = 0;
+    if (status === "stable") score = 3;
+    else if (status === "beta") score = 2;
+    else if (status === "experimental") score = 1;
+    // deprecated gets 0
+
+    if (score > bestScore) {
+      bestScore = score;
+      best = name;
+    }
+  }
+
+  return best;
+}

package/src/core/config.ts

@@ -0,0 +1,84 @@
+import { existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { createJiti } from 'jiti';
+import { BRAND } from './constants.js';
+import type { SegmentsConfig } from './types.js';
+import { segmentsConfigSchema } from './schema.js';
+
+const DEFAULT_CONFIG: SegmentsConfig = {
+  include: [
+    `src/**/*${BRAND.fileExtension}`,  // *.segment.tsx files
+    'src/**/*.stories.tsx',             // Storybook stories (auto-converted)
+  ],
+  exclude: ['**/node_modules/**'],
+  components: ['src/**/index.tsx', 'src/**/*.tsx'],
+  framework: 'react',
+};
+
+/**
+ * Find the config file in the current directory or parent directories.
+ * Checks for both the current config file name and the legacy name.
+ */
+export function findConfigFile(startDir: string = process.cwd()): string | null {
+  let currentDir = startDir;
+
+  while (currentDir !== dirname(currentDir)) {
+    // Check for current config file name first
+    const configPath = resolve(currentDir, BRAND.configFile);
+    if (existsSync(configPath)) {
+      return configPath;
+    }
+    // Also check for legacy config file name
+    const legacyConfigPath = resolve(currentDir, BRAND.legacyConfigFile);
+    if (existsSync(legacyConfigPath)) {
+      return legacyConfigPath;
+    }
+    currentDir = dirname(currentDir);
+  }
+
+  return null;
+}
+
+/**
+ * Load and validate the config file
+ */
+export async function loadConfig(configPath?: string): Promise<{
+  config: SegmentsConfig;
+  configDir: string;
+}> {
+  const resolvedPath = configPath ?? findConfigFile();
+
+  if (!resolvedPath) {
+    return {
+      config: DEFAULT_CONFIG,
+      configDir: process.cwd(),
+    };
+  }
+
+  try {
+    // Use jiti to load TypeScript config files
+    const jiti = createJiti(import.meta.url, {
+      interopDefault: true,
+    });
+    const rawConfig = await jiti.import(resolvedPath);
+
+    const result = segmentsConfigSchema.safeParse(rawConfig);
+
+    if (!result.success) {
+      const errors = result.error.errors
+        .map((e) => `  - ${e.path.join('.')}: ${e.message}`)
+        .join('\n');
+      throw new Error(`Invalid config in ${resolvedPath}:\n${errors}`);
+    }
+
+    return {
+      config: { ...DEFAULT_CONFIG, ...result.data },
+      configDir: dirname(resolvedPath),
+    };
+  } catch (error) {
+    if (error instanceof Error && error.message.includes('Invalid config')) {
+      throw error;
+    }
+    throw new Error(`Failed to load config from ${resolvedPath}: ${error}`);
+  }
+}

package/src/core/constants.ts

@@ -0,0 +1,111 @@
+/**
+ * Brand constants for easy rebranding if domain availability requires it.
+ * All naming throughout the codebase should reference these constants.
+ */
+export const BRAND = {
+  /** Display name (e.g., "Fragments") */
+  name: "Fragments",
+
+  /** Lowercase name for file paths and CLI (e.g., "fragments") */
+  nameLower: "fragments",
+
+  /** File extension for fragment definition files (e.g., ".fragment.tsx") */
+  fileExtension: ".fragment.tsx",
+
+  /** Legacy file extension for segments (still supported for migration) */
+  legacyFileExtension: ".segment.tsx",
+
+  /** JSON file extension for compiled output */
+  jsonExtension: ".fragment.json",
+
+  /** Default output file name (e.g., "fragments.json") */
+  outFile: "fragments.json",
+
+  /** Config file name (e.g., "fragments.config.ts") */
+  configFile: "fragments.config.ts",
+
+  /** Legacy config file name (still supported for migration) */
+  legacyConfigFile: "segments.config.ts",
+
+  /** CLI command name (e.g., "fragments") */
+  cliCommand: "fragments",
+
+  /** Package scope (e.g., "@fragments") */
+  packageScope: "@fragments",
+
+  /** Directory for storing fragments, registry, and cache */
+  dataDir: ".fragments",
+
+  /** Components subdirectory within .fragments/ */
+  componentsDir: "components",
+
+  /** Registry file name */
+  registryFile: "registry.json",
+
+  /** Context file name (AI-ready markdown) */
+  contextFile: "context.md",
+
+  /** Screenshots subdirectory */
+  screenshotsDir: "screenshots",
+
+  /** Cache subdirectory (gitignored) */
+  cacheDir: "cache",
+
+  /** Diff output subdirectory (gitignored) */
+  diffDir: "diff",
+
+  /** Manifest filename */
+  manifestFile: "manifest.json",
+
+  /** Prefix for localStorage keys (e.g., "fragments-") */
+  storagePrefix: "fragments-",
+
+  /** Static viewer HTML file name */
+  viewerHtmlFile: "fragments-viewer.html",
+
+  /** MCP tool name prefix (e.g., "fragments_") */
+  mcpToolPrefix: "fragments_",
+
+  /** File extension for recipe definition files */
+  recipeFileExtension: ".recipe.ts",
+
+  /** Vite plugin namespace */
+  vitePluginNamespace: "fragments-core-shim",
+} as const;
+
+export type Brand = typeof BRAND;
+
+/**
+ * Default configuration values for the service.
+ * These can be overridden in fragments.config.ts
+ */
+export const DEFAULTS = {
+  /** Default viewport dimensions */
+  viewport: {
+    width: 1280,
+    height: 800,
+  },
+
+  /** Default diff threshold (percentage) */
+  diffThreshold: 5,
+
+  /** Browser pool size */
+  poolSize: 3,
+
+  /** Idle timeout before browser shutdown (ms) - 5 minutes */
+  idleTimeoutMs: 5 * 60 * 1000,
+
+  /** Delay after render before capture (ms) */
+  captureDelayMs: 100,
+
+  /** Font loading timeout (ms) */
+  fontTimeoutMs: 3000,
+
+  /** Default theme */
+  theme: "light" as const,
+
+  /** Dev server port */
+  port: 6006,
+} as const;
+
+export type Defaults = typeof DEFAULTS;