@synergy-design-system/mcp 0.1.0 → 1.1.0

package/dist/utilities/storybook/configs.js

@@ -0,0 +1,85 @@
+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 () => 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 () => 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 () => Object.keys(templateStories),
+    outputPath: staticStylesPath,
+};

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

@@ -0,0 +1,26 @@
+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

@@ -0,0 +1,97 @@
+/* eslint-disable no-console */
+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

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,14 @@
+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

@@ -0,0 +1,196 @@
+/* eslint-disable no-console */
+import { dirname } from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { chromium } from 'playwright';
+import prettier from 'prettier';
+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 storyMetadata = await page.evaluate(() => Array.from(document.querySelectorAll('.sb-anchor'))
+                .map((story, index) => {
+                const description = story.querySelector(':scope > p')?.textContent || '';
+                const exampleSource = story.querySelector('.sb-story #root-inner')?.innerHTML || '';
+                const heading = story.querySelector('h3')?.textContent || '';
+                const hasIframe = !!story.querySelector('.sb-story iframe');
+                return {
+                    description,
+                    exampleSource,
+                    hasIframe,
+                    heading,
+                    index,
+                };
+            })
+                .filter(x => x.heading));
+            // 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);
+                        const frame = await 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}"`);
+                    }
+                }
+                // 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

@@ -0,0 +1,29 @@
+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

@@ -0,0 +1,139 @@
+/* eslint-disable no-console */
+import { createServer } from 'http';
+import { promisify } from 'node:util';
+import { exec } from 'node:child_process';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+// eslint-disable-next-line import/no-extraneous-dependencies
+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

@@ -0,0 +1,22 @@
+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

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

package/dist/utilities/styles.d.ts

@@ -0,0 +1,6 @@
+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[]>;

package/dist/utilities/styles.js

@@ -0,0 +1,24 @@
+import fs from 'node:fs/promises';
+import { staticStylesPath, stylesPath, } from './config.js';
+import { getAbsolutePath } from './file.js';
+import { getStructuredMetaData, } from './metadata.js';
+export const getStylesMetaData = async () => {
+    const data = await getStructuredMetaData(stylesPath);
+    const additionalData = await getStructuredMetaData(staticStylesPath);
+    return [
+        ...data,
+        ...additionalData,
+    ];
+};
+/**
+ * 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 const getAvailableStyles = async () => {
+    const absolutePath = getAbsolutePath(`${stylesPath}`);
+    const files = await fs.readdir(absolutePath, { withFileTypes: true });
+    const styles = files
+        .filter(file => file.isFile() && file.name !== 'index.css' && file.name.endsWith('css'))
+        .map(file => file.name.replace('.css', ''));
+    return styles;
+};

package/dist/utilities/templates.d.ts

@@ -0,0 +1,12 @@
+export declare const getTemplateMetaData: () => Promise<(import("./metadata.js").MetadataFile | null)[]>;
+/**
+ * Get a list of all available templates in the Synergy Design System.
+ * @returns A list of all available templates in the Synergy Design System.
+ */
+export declare const getAvailableTemplates: () => Promise<string[]>;
+/**
+ * Get information about a specific template in the Synergy Design System.
+ * @param template The name of the template to get information about, e.g., 'appshell'.
+ * @returns Structured metadata for the specified template.
+ */
+export declare const getInfoForTemplate: (template: string) => Promise<(import("./metadata.js").MetadataFile | null)[]>;