@auto-engineer/design-system-importer 0.4.8 → 0.5.0

package/src/FigmaComponentsBuilder.ts

@@ -1,11 +1,31 @@
 import * as dotenv from 'dotenv';
 import * as Figma from 'figma-api';
+import createDebug from 'debug';
+
+const debug = createDebug('design-system-importer:figma-builder');
+const debugComponents = createDebug('design-system-importer:figma-builder:components');
+const debugFilters = createDebug('design-system-importer:figma-builder:filters');
+const debugAPI = createDebug('design-system-importer:figma-builder:api');
+const debugTree = createDebug('design-system-importer:figma-builder:tree');
 
 dotenv.config();
 
+debug('Initializing FigmaComponentsBuilder module');
+
+// Add timeout wrapper for Figma API calls
+const withTimeout = <T>(promise: Promise<T>, timeoutMs: number = 10000): Promise<T> => {
+  return Promise.race([
+    promise,
+    new Promise<T>((_, reject) =>
+      setTimeout(() => reject(new Error(`Figma API request timed out after ${timeoutMs}ms`)), timeoutMs),
+    ),
+  ]);
+};
+
 const figmaApi = new Figma.Api({
   personalAccessToken: process.env.FIGMA_PERSONAL_TOKEN as string,
 });
+debug('Figma API initialized with personal access token');
 
 export interface FigmaComponent {
   name: string;
@@ -26,47 +46,103 @@ interface FigmaNode {
 export class FigmaComponentsBuilder {
   components: FigmaComponent[] = [];
 
+  constructor() {
+    debug('FigmaComponentsBuilder instance created');
+    debugComponents('Initial components array: empty');
+  }
+
   async withFigmaComponents() {
+    debugAPI('Fetching Figma components from file: %s', process.env.FIGMA_FILE_ID);
+
+    if (
+      process.env.FIGMA_PERSONAL_TOKEN?.trim() === '' ||
+      process.env.FIGMA_FILE_ID?.trim() === '' ||
+      process.env.FIGMA_PERSONAL_TOKEN === undefined ||
+      process.env.FIGMA_FILE_ID === undefined
+    ) {
+      debugAPI('Missing Figma credentials. FIGMA_PERSONAL_TOKEN or FIGMA_FILE_ID not set');
+      console.warn('Skipping Figma import: Missing FIGMA_PERSONAL_TOKEN or FIGMA_FILE_ID in environment');
+      return this;
+    }
+
     try {
+      debugAPI('Making API call to getFileComponents...');
       // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-      const response = await figmaApi.getFileComponents({ file_key: process.env.FIGMA_FILE_ID });
+      const response = await withTimeout(figmaApi.getFileComponents({ file_key: process.env.FIGMA_FILE_ID }), 10000);
+      debugAPI('API response received');
       // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
       if (response.meta.components.length > 0) {
         // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-        console.log(JSON.stringify(response.meta.components.length, null, 2));
+        debugComponents('Found %d components in Figma file', response.meta.components.length);
         // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment,@typescript-eslint/no-unsafe-call,@typescript-eslint/no-unsafe-member-access
         this.components = response.meta.components.map(
-          (component: { name: string; description: string; thumbnail_url: string }) => ({
-            name: component.name,
-            description: component.description,
-            thumbnail: component.thumbnail_url,
-          }),
+          (component: { name: string; description: string; thumbnail_url: string }) => {
+            debugComponents('Processing component: %s', component.name);
+            return {
+              name: component.name,
+              description: component.description,
+              thumbnail: component.thumbnail_url,
+            };
+          },
         );
+        debugComponents('Successfully mapped %d components', this.components.length);
+      } else {
+        debugComponents('No components found in Figma file');
       }
     } catch (e) {
-      console.error(e);
+      debugAPI('ERROR: Failed to fetch Figma components: %O', e);
+      console.error('Failed to fetch Figma components:', e);
     }
+    debugComponents('withFigmaComponents complete, total components: %d', this.components.length);
     return this;
   }
 
   async withFigmaComponentSets() {
+    debugAPI('Fetching Figma component sets from file: %s', process.env.FIGMA_FILE_ID);
+
+    if (
+      process.env.FIGMA_PERSONAL_TOKEN?.trim() === '' ||
+      process.env.FIGMA_FILE_ID?.trim() === '' ||
+      process.env.FIGMA_PERSONAL_TOKEN === undefined ||
+      process.env.FIGMA_FILE_ID === undefined
+    ) {
+      debugAPI('Missing Figma credentials. FIGMA_PERSONAL_TOKEN or FIGMA_FILE_ID not set');
+      console.warn('Skipping Figma import: Missing FIGMA_PERSONAL_TOKEN or FIGMA_FILE_ID in environment');
+      return this;
+    }
+
     try {
+      debugAPI('Making API call to getFileComponentSets...');
       // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-      const response = await figmaApi.getFileComponentSets({ file_key: process.env.FIGMA_FILE_ID });
+      const response = await withTimeout(figmaApi.getFileComponentSets({ file_key: process.env.FIGMA_FILE_ID }), 10000);
+      debugAPI('API response received');
       // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
       if (response.meta.component_sets.length > 0) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+        debugComponents('Found %d component sets in Figma file', response.meta.component_sets.length);
         // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment,@typescript-eslint/no-unsafe-call,@typescript-eslint/no-unsafe-member-access
         this.components = response.meta.component_sets.map(
-          (component: { name: string; description: string; thumbnail_url: string }) => ({
-            name: component.name,
-            description: component.description ?? 'N/A',
-            thumbnail: component.thumbnail_url ?? 'N/A',
-          }),
+          (component: { name: string; description: string; thumbnail_url: string }) => {
+            debugComponents('Processing component set: %s', component.name);
+            const mapped = {
+              name: component.name,
+              description: component.description ?? 'N/A',
+              thumbnail: component.thumbnail_url ?? 'N/A',
+            };
+            debugComponents('  - Description: %s', mapped.description.substring(0, 50));
+            debugComponents('  - Has thumbnail: %s', mapped.thumbnail !== 'N/A');
+            return mapped;
+          },
         );
+        debugComponents('Successfully mapped %d component sets', this.components.length);
+      } else {
+        debugComponents('No component sets found in Figma file');
       }
     } catch (e) {
-      console.error(e);
+      debugAPI('ERROR: Failed to fetch Figma component sets: %O', e);
+      console.error('Failed to fetch Figma component sets:', e);
     }
+    debugComponents('withFigmaComponentSets complete, total components: %d', this.components.length);
     return this;
   }
 
@@ -81,73 +157,122 @@ export class FigmaComponentsBuilder {
   // }
 
   withFilteredNamesForShadcn(): void {
+    debugFilters('Applying Shadcn name filter to %d components', this.components.length);
+    const originalCount = this.components.length;
     this.components = this.components
       .map((comp: FigmaComponent): FigmaComponent | null => {
-        if (!comp?.name) return null;
+        if (!comp?.name) {
+          debugFilters('Skipping component with no name');
+          return null;
+        }
 
         let str = comp.name.trim();
+        debugFilters('Processing component name: %s', str);
 
         if (str.includes('/')) {
+          const original = str;
           str = str.split('/')[0].trim();
+          debugFilters('  Split by /: %s -> %s', original, str);
         } else {
+          const original = str;
           str = str.split(' ')[0].trim();
+          debugFilters('  Split by space: %s -> %s', original, str);
         }
 
         if (str.length > 0) {
-          str = str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
+          const capitalized = str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
+          const final = capitalized.toLowerCase();
+          debugFilters('  Normalized: %s -> %s', str, final);
+          return {
+            ...comp,
+            name: final,
+          };
         } else {
+          debugFilters('  Empty string after processing, skipping');
           return null;
         }
-
-        return {
-          ...comp,
-          name: str.toLowerCase(),
-        };
       })
       .filter((c: FigmaComponent | null): c is FigmaComponent => Boolean(c));
+    debugFilters('Shadcn filter complete: %d -> %d components', originalCount, this.components.length);
   }
 
   withFilter(filter: FilterFunctionType): void {
+    debugFilters('Applying custom filter function to %d components', this.components.length);
+    const originalCount = this.components.length;
     try {
       this.components = filter(this.components);
+      debugFilters('Custom filter applied successfully: %d -> %d components', originalCount, this.components.length);
     } catch (e) {
+      debugFilters('ERROR: Failed to apply custom filter: %O', e);
       console.error('Error applying custom filter:', e);
     }
   }
 
   async withAllFigmaInstanceNames() {
+    debugAPI('Fetching all Figma instance names from file: %s', process.env.FIGMA_FILE_ID);
+
+    if (
+      process.env.FIGMA_PERSONAL_TOKEN?.trim() === '' ||
+      process.env.FIGMA_FILE_ID?.trim() === '' ||
+      process.env.FIGMA_PERSONAL_TOKEN === undefined ||
+      process.env.FIGMA_FILE_ID === undefined
+    ) {
+      debugAPI('Missing Figma credentials. FIGMA_PERSONAL_TOKEN or FIGMA_FILE_ID not set');
+      console.warn('Skipping Figma import: Missing FIGMA_PERSONAL_TOKEN or FIGMA_FILE_ID in environment');
+      return this;
+    }
+
     try {
       /// ----
       const usedComponentMap = new Map<string, { name: string; description: string; thumbnail: string }>();
+      debugTree('Created component map for tracking unique instances');
 
+      debugAPI('Making API call to getFile with depth: 1...');
       // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-      const { document } = await figmaApi.getFile({
-        file_key: process.env.FIGMA_FILE_ID,
-        depth: 1,
-      });
+      const { document } = await withTimeout(
+        figmaApi.getFile({
+          file_key: process.env.FIGMA_FILE_ID,
+          depth: 1,
+        }),
+        10000,
+      );
+      debugAPI('File document received, starting tree walk');
+
+      // eslint-disable-next-line complexity
+      function walkTree(node: FigmaNode, depth: number = 0) {
+        const indent = '  '.repeat(depth);
+        debugTree('%sVisiting node: %s (type: %s)', indent, node.name, node.type);
 
-      function walkTree(node: FigmaNode) {
         if (node.type === 'INSTANCE' && Boolean(node.name)) {
           if (!usedComponentMap.has(node.name)) {
+            debugTree('%s  -> Found new instance: %s', indent, node.name);
             usedComponentMap.set(node.name, {
               name: node.name,
               description: node.description ?? '',
               thumbnail: node.thumbnail_url ?? '',
             });
+            debugTree('%s     Description: %s', indent, node.description ? 'present' : 'empty');
+            debugTree('%s     Thumbnail: %s', indent, node.thumbnail_url ? 'present' : 'missing');
+          } else {
+            debugTree('%s  -> Instance already tracked: %s', indent, node.name);
           }
         }
 
         // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
         if (node.children) {
+          debugTree('%s  Has %d children', indent, node.children.length);
           for (const child of node.children) {
-            walkTree(child);
+            walkTree(child, depth + 1);
           }
         }
       }
 
+      debugTree('Starting tree walk from document root');
       walkTree(document);
+      debugTree('Tree walk complete');
 
       this.components = Array.from(usedComponentMap.values());
+      debugComponents('Extracted %d unique component instances', this.components.length);
 
       /// ----
 
@@ -196,12 +321,20 @@ export class FigmaComponentsBuilder {
       //   );
       // }
     } catch (e) {
-      console.error(e);
+      debugAPI('ERROR: Failed to fetch Figma instance names: %O', e);
+      console.error('Failed to fetch Figma instance names:', e);
     }
+    debugComponents('withAllFigmaInstanceNames complete, total components: %d', this.components.length);
     return this;
   }
 
   build() {
+    debug('Building final component list');
+    debugComponents('Returning %d components', this.components.length);
+    if (this.components.length > 0) {
+      debugComponents('First component: %s', this.components[0].name);
+      debugComponents('Last component: %s', this.components[this.components.length - 1].name);
+    }
     return this.components;
   }
 }

package/src/cli-manifest.ts

@@ -0,0 +1,18 @@
+import type { CliManifest } from '@auto-engineer/cli/manifest-types';
+
+export const CLI_MANIFEST: CliManifest = {
+  category: '@auto-engineer/design-system-importer',
+  commands: {
+    'import:design-system': {
+      handler: () => import('./commands/import-design-system'),
+      description: 'Import Figma design system',
+      usage: 'import:design-system <src> <mode> [filter]',
+      examples: ['$ auto import:design-system ./.context WITH_COMPONENT_SETS ./shadcn-filter.ts'],
+      args: [
+        { name: 'src', description: 'Source directory for design system', required: true },
+        { name: 'mode', description: 'Import mode (e.g., WITH_COMPONENT_SETS)', required: true },
+        { name: 'filter', description: 'Optional filter file', required: false },
+      ],
+    },
+  },
+};

package/src/commands/import-design-system.ts

@@ -1,6 +1,12 @@
 import { type CommandHandler, type Command, type Event } from '@auto-engineer/message-bus';
 import { importDesignSystemComponentsFromFigma, ImportStrategy, type FilterFunctionType } from '../index';
 import { FilterLoader } from '../utils/FilterLoader';
+import createDebug from 'debug';
+
+const debug = createDebug('design-system-importer:command');
+const debugFilter = createDebug('design-system-importer:command:filter');
+const debugHandler = createDebug('design-system-importer:command:handler');
+const debugResult = createDebug('design-system-importer:command:result');
 
 export type ImportDesignSystemCommand = Command<
   'ImportDesignSystem',
@@ -27,31 +33,51 @@ export type DesignSystemImportFailedEvent = Event<
 >;
 
 // Handler
-export async function handleImportDesignSystemCommand(
+// eslint-disable-next-line complexity
+async function handleImportDesignSystemCommandInternal(
   command: ImportDesignSystemCommand,
 ): Promise<DesignSystemImportedEvent | DesignSystemImportFailedEvent> {
   const { outputDir, strategy, filterPath } = command.data;
 
+  debug('Handling ImportDesignSystemCommand');
+  debug('  Output directory: %s', outputDir);
+  debug('  Strategy: %s', strategy ?? 'default');
+  debug('  Filter path: %s', filterPath ?? 'none');
+  debug('  Request ID: %s', command.requestId);
+  debug('  Correlation ID: %s', command.correlationId ?? 'none');
+
   try {
     const resolvedStrategy = strategy ? ImportStrategy[strategy] : ImportStrategy.WITH_COMPONENT_SETS;
+    debugHandler('Resolved strategy: %s', resolvedStrategy);
 
     let filterFn: FilterFunctionType | undefined;
     let loader: FilterLoader | undefined;
     if (typeof filterPath === 'string' && filterPath.trim().length > 0) {
+      debugFilter('Loading custom filter from: %s', filterPath);
       try {
         loader = new FilterLoader();
+        debugFilter('FilterLoader instance created');
         filterFn = await loader.loadFilter(filterPath);
+        debugFilter('Filter function loaded successfully');
       } catch (e) {
+        debugFilter('ERROR: Failed to load filter from %s: %O', filterPath, e);
         console.warn(`Could not import filter from ${filterPath}. Skipping custom filter.`, e);
       } finally {
-        if (loader) loader.cleanup();
+        if (loader) {
+          debugFilter('Cleaning up FilterLoader');
+          loader.cleanup();
+        }
       }
+    } else {
+      debugFilter('No filter path provided, proceeding without custom filter');
     }
 
+    debugHandler('Calling importDesignSystemComponentsFromFigma...');
     await importDesignSystemComponentsFromFigma(outputDir, resolvedStrategy, filterFn);
+    debugHandler('Import completed successfully');
     console.log(`Design system files processed to ${outputDir}`);
 
-    return {
+    const successEvent: DesignSystemImportedEvent = {
       type: 'DesignSystemImported',
       data: {
         outputDir,
@@ -60,11 +86,16 @@ export async function handleImportDesignSystemCommand(
       requestId: command.requestId,
       correlationId: command.correlationId,
     };
+    debugResult('Returning success event: DesignSystemImported');
+    debugResult('  Output directory: %s', outputDir);
+    return successEvent;
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : String(error);
+    debugHandler('ERROR: Design system import failed: %O', error);
+    debugResult('Error message: %s', errorMessage);
     console.error('Error importing design system:', error);
 
-    return {
+    const failureEvent: DesignSystemImportFailedEvent = {
       type: 'DesignSystemImportFailed',
       data: {
         error: errorMessage,
@@ -74,17 +105,82 @@ export async function handleImportDesignSystemCommand(
       requestId: command.requestId,
       correlationId: command.correlationId,
     };
+    debugResult('Returning failure event: DesignSystemImportFailed');
+    debugResult('  Error: %s', errorMessage);
+    debugResult('  Output directory: %s', outputDir);
+    return failureEvent;
   }
 }
 
 export const importDesignSystemCommandHandler: CommandHandler<ImportDesignSystemCommand> = {
   name: 'ImportDesignSystem',
   handle: async (command: ImportDesignSystemCommand): Promise<void> => {
-    const result = await handleImportDesignSystemCommand(command);
+    debug('CommandHandler executing for ImportDesignSystem');
+    const result = await handleImportDesignSystemCommandInternal(command);
     if (result.type === 'DesignSystemImported') {
+      debug('Command handler completed: success');
       console.log('Design system imported successfully');
     } else {
+      debug('Command handler completed: failure - %s', result.data.error);
       console.error(`Failed: ${result.data.error}`);
     }
   },
 };
+
+// CLI arguments interface
+interface CliArgs {
+  _: string[];
+  strategy?: 'WITH_COMPONENTS' | 'WITH_COMPONENT_SETS' | 'WITH_ALL_FIGMA_INSTANCES';
+  filter?: string;
+  [key: string]: unknown;
+}
+
+// Type guard to check if it's an ImportDesignSystemCommand
+function isImportDesignSystemCommand(obj: unknown): obj is ImportDesignSystemCommand {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    'type' in obj &&
+    'data' in obj &&
+    (obj as { type: unknown }).type === 'ImportDesignSystem'
+  );
+}
+
+// Default export for CLI usage
+export default async (commandOrArgs: ImportDesignSystemCommand | CliArgs) => {
+  let command: ImportDesignSystemCommand;
+
+  if (isImportDesignSystemCommand(commandOrArgs)) {
+    command = commandOrArgs;
+  } else if ('outputDir' in commandOrArgs) {
+    // Handle message bus format
+    const args = commandOrArgs as { outputDir?: string; strategy?: string; filterPath?: string };
+    command = {
+      type: 'ImportDesignSystem' as const,
+      data: {
+        outputDir: args.outputDir ?? '.context',
+        strategy: args.strategy as keyof typeof ImportStrategy | undefined,
+        filterPath: args.filterPath,
+      },
+      timestamp: new Date(),
+    };
+  } else {
+    // Handle traditional CLI args format
+    command = {
+      type: 'ImportDesignSystem' as const,
+      data: {
+        outputDir: commandOrArgs._?.[0] ?? '.context',
+        strategy: commandOrArgs._?.[1] as keyof typeof ImportStrategy | undefined,
+        filterPath: commandOrArgs._?.[2],
+      },
+      timestamp: new Date(),
+    };
+  }
+
+  const result = await handleImportDesignSystemCommandInternal(command);
+  if (result.type === 'DesignSystemImported') {
+    console.log('Design system imported successfully');
+  } else {
+    console.error(`Failed: ${result.data.error}`);
+  }
+};