@synergy-design-system/mcp 2.15.0 → 3.0.1

package/dist/utilities/storybook/configs.js

@@ -1,85 +0,0 @@
-import storybookOutput from '@synergy-design-system/docs/dist/index.json' with { type: 'json' };
-import { staticComponentPath, staticStylesPath, templatesPath, } from '../config.js';
-/**
- * Get stories from Storybook output based on a prefix.
- * @param prefix Prefix to filter stories by
- * @returns List of stories matching the prefix
- */
-const getStoriesFromStorybook = (prefix) => {
-    const foundStories = Object
-        .entries(storybookOutput.entries)
-        .filter(([key]) => key.startsWith(`${prefix}-`) && key.endsWith('-docs'))
-        .map(([, value]) => value)
-        .reduce((acc, story) => {
-        const componentName = story.id.split('--')[0].replace(`${prefix}-`, '');
-        acc[componentName] = story.id;
-        return acc;
-    }, {});
-    return foundStories;
-};
-const componentStories = getStoriesFromStorybook('components');
-const styleStories = getStoriesFromStorybook('styles');
-const templateStories = getStoriesFromStorybook('templates');
-/**
- * Configuration for scraping component documentation
- */
-export const componentScrapingConfig = {
-    formatContent: (component, stories) => {
-        const content = stories.map(story => `
-## ${story.heading}
-
-${story.description}
-
-\`\`\`html
-${story.example}
-\`\`\`
-`).join('\n---\n');
-        return content;
-    },
-    generateOutputPath: (component) => `${staticComponentPath}/${component}/docs.md`,
-    generateStoryId: (component) => componentStories[component],
-    getItems: async () => Promise.resolve(Object.keys(componentStories)),
-    outputPath: staticComponentPath,
-};
-/**
- * Configuration for scraping styles documentation
- */
-export const stylesScrapingConfig = {
-    formatContent: (style, stories) => {
-        const content = stories.map(story => `
-## ${story.heading}
-
-${story.description}
-
-\`\`\`html
-${story.example}
-\`\`\`
-`).join('\n---\n');
-        return content;
-    },
-    generateOutputPath: (style) => `${staticStylesPath}/${style}.md`,
-    generateStoryId: (component) => styleStories[component],
-    getItems: async () => Promise.resolve(Object.keys(styleStories)),
-    outputPath: staticStylesPath,
-};
-/**
- * Configuration for scraping template documentation
- */
-export const templateScrapingConfig = {
-    formatContent: (template, stories) => {
-        const content = stories.map(story => `
-## ${story.heading}
-
-${story.description}
-
-\`\`\`html
-${story.example}
-\`\`\`
-`).join('\n---\n');
-        return content;
-    },
-    generateOutputPath: (template) => `${templatesPath}/${template}.md`,
-    generateStoryId: (component) => templateStories[component],
-    getItems: async () => Promise.resolve(Object.keys(templateStories)),
-    outputPath: staticStylesPath,
-};

package/dist/utilities/storybook/docs-scraper.d.ts

@@ -1,26 +0,0 @@
-import { ScrapingConfig } from './types.js';
-export declare class DocsScraper {
-    private baseUrl;
-    constructor(baseUrl?: string);
-    /**
-     * Run the scraping process for a specific configuration
-     */
-    scrapeWithConfig(config: ScrapingConfig): Promise<void>;
-    /**
-     * Scrape component documentation
-     */
-    scrapeComponents(): Promise<void>;
-    /**
-     * Scrape styles documentation
-     */
-    scrapeStyles(): Promise<void>;
-    /**
-     * Scrape styles documentation
-     */
-    scrapeTemplates(): Promise<void>;
-    /**
-     * Scrape all documentation types
-     */
-    scrapeAll(): Promise<void>;
-}
-export declare function runDocsScraper(type?: 'components' | 'styles' | 'templates' | 'all', baseUrl?: string): Promise<void>;

package/dist/utilities/storybook/docs-scraper.js

@@ -1,96 +0,0 @@
-import { StorybookScraper } from './scraper.js';
-import { componentScrapingConfig, stylesScrapingConfig, templateScrapingConfig, } from './configs.js';
-export class DocsScraper {
-    baseUrl;
-    constructor(baseUrl = 'http://localhost:6006') {
-        this.baseUrl = baseUrl;
-    }
-    /**
-     * Run the scraping process for a specific configuration
-     */
-    async scrapeWithConfig(config) {
-        try {
-            console.log(`Using Storybook server at ${this.baseUrl}`);
-            // Create scraper and run
-            const scraper = new StorybookScraper(config);
-            await scraper.scrapeAll(this.baseUrl);
-        }
-        catch (error) {
-            console.error('Error during scraping process:', error);
-            throw error;
-        }
-    }
-    /**
-     * Scrape component documentation
-     */
-    async scrapeComponents() {
-        console.log('Starting component documentation scraping...');
-        await this.scrapeWithConfig(componentScrapingConfig);
-    }
-    /**
-     * Scrape styles documentation
-     */
-    async scrapeStyles() {
-        console.log('Starting styles documentation scraping...');
-        await this.scrapeWithConfig(stylesScrapingConfig);
-    }
-    /**
-     * Scrape styles documentation
-     */
-    async scrapeTemplates() {
-        console.log('Starting templates documentation scraping...');
-        await this.scrapeWithConfig(templateScrapingConfig);
-    }
-    /**
-     * Scrape all documentation types
-     */
-    async scrapeAll() {
-        console.log('Starting comprehensive documentation scraping...');
-        try {
-            console.log(`Using Storybook server at ${this.baseUrl}`);
-            // Scrape components
-            console.log('Scraping component documentation...');
-            const componentScraper = new StorybookScraper(componentScrapingConfig);
-            await componentScraper.scrapeAll(this.baseUrl);
-            // Scrape styles
-            console.log('Scraping styles documentation...');
-            const stylesScraper = new StorybookScraper(stylesScrapingConfig);
-            await stylesScraper.scrapeAll(this.baseUrl);
-            // Scrape templates
-            console.log('Scraping templates documentation...');
-            const templatesScraper = new StorybookScraper(templateScrapingConfig);
-            await templatesScraper.scrapeAll(this.baseUrl);
-            console.log('All documentation scraping completed successfully!');
-        }
-        catch (error) {
-            console.error('Error during comprehensive scraping process:', error);
-            throw error;
-        }
-    }
-}
-// CLI usage helper
-export async function runDocsScraper(type = 'all', baseUrl = 'http://localhost:6006') {
-    const scraper = new DocsScraper(baseUrl);
-    try {
-        switch (type) {
-            case 'components':
-                await scraper.scrapeComponents();
-                break;
-            case 'styles':
-                await scraper.scrapeStyles();
-                break;
-            case 'templates':
-                await scraper.scrapeTemplates();
-                break;
-            case 'all':
-                await scraper.scrapeAll();
-                break;
-            default:
-                throw new Error(`Unknown scraping type: ${type}`);
-        }
-    }
-    catch (error) {
-        console.error('Scraping failed:', error);
-        throw error;
-    }
-}

package/dist/utilities/storybook/index.d.ts

@@ -1,5 +0,0 @@
-export { StaticServerManager } from './storybook-manager.js';
-export { StorybookScraper } from './scraper.js';
-export { DocsScraper, runDocsScraper } from './docs-scraper.js';
-export { componentScrapingConfig, stylesScrapingConfig } from './configs.js';
-export type { ScrapingConfig, ScrapedStory, StorybookServer } from './types.js';

package/dist/utilities/storybook/index.js

@@ -1,4 +0,0 @@
-export { StaticServerManager } from './storybook-manager.js';
-export { StorybookScraper } from './scraper.js';
-export { DocsScraper, runDocsScraper } from './docs-scraper.js';
-export { componentScrapingConfig, stylesScrapingConfig } from './configs.js';

package/dist/utilities/storybook/scraper.d.ts

@@ -1,14 +0,0 @@
-import { Browser } from 'playwright';
-import { ScrapedStory, ScrapingConfig } from './types.js';
-export declare class StorybookScraper {
-    private config;
-    constructor(config: ScrapingConfig);
-    /**
-     * Scrape a single story from Storybook
-     */
-    static scrapeStoryDocs(storyId: string, baseUrl?: string, browser?: Browser): Promise<ScrapedStory[]>;
-    /**
-     * Scrape all configured items and write documentation
-     */
-    scrapeAll(baseUrl?: string): Promise<void>;
-}

package/dist/utilities/storybook/scraper.js

@@ -1,243 +0,0 @@
-import { dirname } from 'node:path';
-import { mkdir, writeFile } from 'node:fs/promises';
-import { chromium } from 'playwright';
-import prettier from 'prettier';
-import storybookOutput from '@synergy-design-system/docs/dist/index.json' with { type: 'json' };
-/**
- * Check if a story should be skipped based on its tags
- * @param storyId The story ID to check (e.g., "components-syn-combobox--async-options")
- * @returns true if the story should be skipped, false otherwise
- */
-function shouldSkipStory(storyId) {
-    const entries = storybookOutput.entries;
-    const storyEntry = entries[storyId];
-    return storyEntry?.tags?.includes('skip_mcp') || false;
-}
-/**
- * Check if a story heading should be skipped by finding the corresponding story ID
- * @param docsStoryId The docs story ID (e.g., "components-syn-combobox--docs")
- * @param heading The story heading (e.g., "Async Options")
- * @returns true if the story should be skipped, false otherwise
- */
-function shouldSkipStoryByHeading(docsStoryId, heading) {
-    // Get the component prefix from docs story ID
-    // (e.g., "components-syn-combobox" from "components-syn-combobox--docs")
-    const componentPrefix = docsStoryId.replace('--docs', '');
-    // Find matching story by converting heading to potential story ID format
-    // Story names are typically converted from "Async Options" to "async-options"
-    const potentialStorySlug = heading.toLowerCase().replace(/\s+/g, '-');
-    const potentialStoryId = `${componentPrefix}--${potentialStorySlug}`;
-    // Check if this potential story ID exists and should be skipped
-    return shouldSkipStory(potentialStoryId);
-}
-export class StorybookScraper {
-    config;
-    constructor(config) {
-        this.config = config;
-    }
-    /**
-     * Scrape a single story from Storybook
-     */
-    static async scrapeStoryDocs(storyId, baseUrl = 'http://localhost:6006', browser) {
-        const shouldCloseBrowser = !browser;
-        const browserInstance = browser || await chromium.launch({
-            headless: true,
-        });
-        const page = await browserInstance.newPage({
-            viewport: {
-                height: 768,
-                width: 1024,
-            },
-        });
-        const scrapingReport = {
-            error: null,
-            foundStories: 0,
-            processedStories: 0,
-            status: 'pending',
-            storyDetails: [],
-            storyId,
-        };
-        try {
-            // Navigate to the Storybook docs page
-            await page.goto(`${baseUrl}/iframe?viewMode=docs&id=${storyId}&globals=`);
-            // Wait for the content to load
-            await page.waitForSelector('.sb-anchor');
-            // Extract the stories metadata first
-            // We get basic info and identify stories that need iframe content
-            const rawStoryMetadata = await page.evaluate(() => Array.from(document.querySelectorAll('.sb-anchor'))
-                // eslint-disable-next-line complexity
-                .map((story, index) => {
-                const description = story.querySelector(':scope > p')?.textContent || '';
-                const heading = story.querySelector('h3')?.textContent || '';
-                const hasIframe = !!story.querySelector('.sb-story iframe');
-                let exampleSource = '';
-                if (!hasIframe) {
-                    // #1152: The example source is usually in the #root-inner element.
-                    // However, for at least one story (tag-group-template), the #root-inner container is missing.
-                    // I am not sure why, but I think a fallback would be just to check the first element for the time being.
-                    const exampleWithRoot = story.querySelector('.sb-story #root-inner')?.innerHTML || '';
-                    const exampleWithoutRoot = story.querySelector('.sb-story > div')?.innerHTML || '';
-                    exampleSource = exampleWithRoot || exampleWithoutRoot;
-                }
-                return {
-                    description,
-                    exampleSource,
-                    hasIframe,
-                    heading,
-                    index,
-                };
-            })
-                .filter(x => x.heading));
-            // Filter out stories that should be skipped based on their tags
-            const storyMetadata = rawStoryMetadata.filter(story => {
-                const shouldSkip = shouldSkipStoryByHeading(storyId, story.heading);
-                if (shouldSkip) {
-                    console.log(`Skipping story "${story.heading}" due to skip_mcp tag`);
-                }
-                return !shouldSkip;
-            });
-            // Process each story and handle iframe content if needed
-            const results = await Promise.all(storyMetadata.map(async (storyMeta) => {
-                let { exampleSource } = storyMeta;
-                // If no inline content and there's an iframe, try to get content from iframe
-                if (!exampleSource && storyMeta.hasIframe) {
-                    try {
-                        const storySection = page.locator('.sb-anchor').nth(storyMeta.index);
-                        // Storybook uses lazy loading, so the iframe may not be loaded until we scroll it into view
-                        await storySection.scrollIntoViewIfNeeded();
-                        await page.waitForTimeout(1000);
-                        const frame = storySection.frameLocator('iframe');
-                        const frameContent = await frame.locator('#root-inner').innerHTML();
-                        exampleSource = frameContent || '';
-                    }
-                    catch (error) {
-                        // If iframe content extraction fails, continue with empty content
-                        console.log(`Failed to extract iframe content for story "${storyMeta.heading}"`, error);
-                    }
-                }
-                // Replace all lit internal comments
-                // Lit comments look like this: <!----> or <!--?lit$SOMENUMBER$-->
-                const example = exampleSource
-                    // Remove comments that start with ?lit (with any content after)
-                    .replace(/<!--\?lit\$[^>]*-->/g, '')
-                    // Remove empty comments
-                    .replace(/<!--\s*-->/g, '')
-                    // Clean up any resulting multiple consecutive whitespace/newlines
-                    .replace(/\n\s*\n\s*\n/g, '\n\n')
-                    // Remove all data attributes as they may be dynamic data
-                    .replace(/ data-[^=]+="[^"]*"/g, '')
-                    // Trim leading/trailing whitespace
-                    .trim();
-                return {
-                    description: storyMeta.description,
-                    example,
-                    heading: storyMeta.heading,
-                };
-            }));
-            // Filter out stories without examples
-            const validResults = results.filter(x => x.heading && x.example);
-            scrapingReport.foundStories = validResults.length;
-            if (validResults.length === 0) {
-                throw new Error(`No stories found for ${storyId}`);
-            }
-            const processedStories = await Promise.all(validResults.map(async (story, index) => {
-                try {
-                    const formattedExample = await prettier.format(story.example, {
-                        parser: 'html',
-                    });
-                    scrapingReport.storyDetails.push({
-                        heading: story.heading,
-                        status: 'success',
-                    });
-                    scrapingReport.processedStories += 1;
-                    return {
-                        description: story.description,
-                        example: formattedExample,
-                        heading: story.heading,
-                    };
-                }
-                catch (error) {
-                    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-                    scrapingReport.storyDetails.push({
-                        error: errorMessage,
-                        heading: story.heading || `Story ${index + 1}`,
-                        status: 'error',
-                    });
-                    throw error;
-                }
-            }));
-            scrapingReport.status = 'success';
-            return processedStories;
-        }
-        catch (error) {
-            scrapingReport.error = error instanceof Error ? error : new Error(String(error));
-            scrapingReport.status = 'error';
-            return [];
-        }
-        finally {
-            await page.close();
-            if (shouldCloseBrowser) {
-                await browserInstance.close();
-            }
-            // Generate final report
-            if (scrapingReport.status !== 'success') {
-                console.log(`📊 Scraping Report for ${storyId}:`);
-                console.log('   Status: ❌ Error');
-                console.log(`   Found Stories: ${scrapingReport.foundStories}`);
-                console.log(`   Processed Stories: ${scrapingReport.processedStories}`);
-                if (scrapingReport.storyDetails.length > 0) {
-                    console.log('   Story Details:');
-                    scrapingReport.storyDetails.forEach((detail, index) => {
-                        const statusIcon = detail.status === 'success' ? '✅' : '❌';
-                        console.log(`     ${index + 1}. ${statusIcon} ${detail.heading}`);
-                        if (detail.error) {
-                            console.log(`        Error: ${detail.error}`);
-                        }
-                    });
-                }
-                if (scrapingReport.error) {
-                    console.log(`   Error Details: ${scrapingReport.error.message}`);
-                }
-                console.log(''); // Empty line for readability
-            }
-        }
-    }
-    /**
-     * Scrape all configured items and write documentation
-     */
-    async scrapeAll(baseUrl = 'http://localhost:6006') {
-        console.log('Starting scraping process...');
-        const items = await this.config.getItems();
-        // Create a single browser instance for all scraping operations
-        const browser = await chromium.launch({
-            headless: true,
-        });
-        try {
-            const scrapedPages = await Promise.all(items.map(async (item) => {
-                const storyId = this.config.generateStoryId(item);
-                const stories = await StorybookScraper.scrapeStoryDocs(storyId, baseUrl, browser);
-                return {
-                    item,
-                    stories,
-                };
-            }));
-            console.log('Writing documentation files...');
-            // Write out the results
-            await Promise.all(scrapedPages.map(async ({ item, stories }) => {
-                const filePath = this.config.generateOutputPath(item);
-                // Ensure the directory exists before writing
-                const dir = dirname(filePath);
-                await mkdir(dir, { recursive: true });
-                const content = await prettier.format(this.config.formatContent(item, stories), {
-                    parser: 'markdown',
-                });
-                await writeFile(filePath, content, 'utf-8');
-            }));
-            console.log('Scraping process completed successfully!');
-        }
-        finally {
-            // Always close the browser, even if an error occurs
-            await browser.close();
-        }
-    }
-}

package/dist/utilities/storybook/storybook-manager.d.ts

@@ -1,29 +0,0 @@
-import { StorybookServer } from './types.js';
-export declare class StaticServerManager {
-    private server;
-    private serverInfo;
-    /**
-     * Check if a port is available
-     */
-    private static isPortAvailable;
-    /**
-     * Find an available port starting from the default port
-     */
-    private static findAvailablePort;
-    /**
-     * Start the static file server for Storybook
-     */
-    start(port?: number): Promise<StorybookServer>;
-    /**
-     * Stop the static server
-     */
-    stop(): Promise<void>;
-    /**
-     * Get the current server information
-     */
-    getServer(): StorybookServer | null;
-    /**
-     * Check if static server is currently running
-     */
-    isRunning(): boolean;
-}

package/dist/utilities/storybook/storybook-manager.js

@@ -1,138 +0,0 @@
-/* eslint-disable @typescript-eslint/no-misused-promises */
-import { createServer } from 'http';
-import { promisify } from 'node:util';
-import { exec } from 'node:child_process';
-import { dirname, resolve } from 'path';
-import { fileURLToPath } from 'url';
-import handler from 'serve-handler';
-const execAsync = promisify(exec);
-// Get current directory for resolving the Storybook build path
-const filename = fileURLToPath(import.meta.url);
-const currentDir = dirname(filename);
-export class StaticServerManager {
-    server = null;
-    serverInfo = null;
-    /**
-     * Check if a port is available
-     */
-    static async isPortAvailable(port) {
-        try {
-            const { stdout } = await execAsync(`lsof -ti:${port}`);
-            return stdout.trim() === '';
-        }
-        catch {
-            return true;
-        }
-    }
-    /**
-     * Find an available port starting from the default port
-     */
-    static async findAvailablePort(startPort = 6006) {
-        let port = startPort;
-        // eslint-disable-next-line no-await-in-loop
-        while (!(await StaticServerManager.isPortAvailable(port))) {
-            port += 1;
-            if (port > startPort + 100) {
-                throw new Error('Could not find available port for static server');
-            }
-        }
-        return port;
-    }
-    /**
-     * Start the static file server for Storybook
-     */
-    async start(port = 6006) {
-        if (this.serverInfo?.isRunning) {
-            console.log('Static server is already running');
-            return this.serverInfo;
-        }
-        const availablePort = await StaticServerManager.findAvailablePort(port);
-        const url = `http://localhost:${availablePort}`;
-        const storybookDistPath = resolve(currentDir, '../../../../docs/dist');
-        console.log(`Starting static server on port ${availablePort}...`);
-        console.log(`Serving files from: ${storybookDistPath}`);
-        this.server = createServer((request, response) => {
-            // Add custom URL rewriting before serve-handler
-            const originalUrl = request.url || '';
-            // Handle iframe.html -> iframe rewrite manually
-            if (originalUrl.startsWith('/iframe.html')) {
-                const rewrittenUrl = originalUrl.replace('/iframe.html', '/iframe');
-                request.url = rewrittenUrl;
-            }
-            return handler(request, response, {
-                headers: [
-                    {
-                        headers: [
-                            {
-                                key: 'Cache-Control',
-                                value: 'public, max-age=3600',
-                            },
-                        ],
-                        source: '**',
-                    },
-                ],
-                public: storybookDistPath,
-            });
-        });
-        // Start listening and wait for the server to be ready
-        await new Promise((resolvePromise, reject) => {
-            if (!this.server) {
-                reject(new Error('Server instance not created'));
-                return;
-            }
-            // Handle server errors
-            this.server.on('error', (error) => {
-                console.error('Static server error:', error);
-                reject(error);
-            });
-            // Server is ready when listening event fires
-            this.server.on('listening', () => {
-                console.log(`✓ Static server started successfully at ${url}`);
-                resolvePromise();
-            });
-            // Start the server
-            this.server.listen(availablePort);
-        });
-        this.serverInfo = {
-            isRunning: true,
-            port: availablePort,
-            url,
-        };
-        console.log(`Static server ready at ${url}`);
-        return this.serverInfo;
-    }
-    /**
-     * Stop the static server
-     */
-    async stop() {
-        if (!this.server || !this.serverInfo) {
-            console.log('No static server to stop');
-            return;
-        }
-        console.log('Stopping static server...');
-        await new Promise((resolvePromise) => {
-            if (!this.server) {
-                resolvePromise();
-                return;
-            }
-            this.server.close(() => {
-                this.serverInfo = null;
-                this.server = null;
-                console.log('Static server stopped successfully');
-                resolvePromise();
-            });
-        });
-    }
-    /**
-     * Get the current server information
-     */
-    getServer() {
-        return this.serverInfo;
-    }
-    /**
-     * Check if static server is currently running
-     */
-    isRunning() {
-        return this.serverInfo?.isRunning ?? false;
-    }
-}

package/dist/utilities/storybook/types.d.ts

@@ -1,22 +0,0 @@
-export interface ScrapingConfig {
-    /** The output directory path */
-    outputPath: string;
-    /** Function to get the list of items to scrape */
-    getItems: () => Promise<string[]> | string[];
-    /** Function to generate the story ID from an item */
-    generateStoryId: (item: string) => string;
-    /** Function to generate the output file path from an item */
-    generateOutputPath: (item: string) => string;
-    /** Function to format the scraped content */
-    formatContent: (item: string, stories: ScrapedStory[]) => string;
-}
-export interface ScrapedStory {
-    heading: string;
-    description: string;
-    example: string;
-}
-export interface StorybookServer {
-    port: number;
-    url: string;
-    isRunning: boolean;
-}

package/dist/utilities/storybook/types.js

@@ -1 +0,0 @@
-export {};

package/dist/utilities/styles.d.ts

@@ -1,6 +0,0 @@
-export declare const getStylesMetaData: () => Promise<(import("./metadata.js").MetadataFile | null)[]>;
-/**
- * Get a list of all available styles in the Synergy Design System.
- * @returns A list of all available styles in the Synergy Design System.
- */
-export declare const getAvailableStyles: () => Promise<string[]>;