@agentskillkit/agent-skills 1.0.1 → 3.2.2

package/.agent/skills/studio/scripts-js/utils/config-loader.js

@@ -0,0 +1,164 @@
+/**
+ * Studio Config Loader - Custom Page Patterns
+ * =============================================
+ * Loads user-defined configuration for custom page type patterns
+ * Supports .studiorc.json and studio-config.json
+ */
+
+import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Default config file names (in priority order)
+ */
+const CONFIG_FILES = [
+    '.studiorc.json',
+    'studio-config.json',
+    '.studiorc'
+];
+
+/**
+ * @typedef {Object} CustomPattern
+ * @property {string[]} keywords - Keywords to match
+ * @property {string} type - Page type name to return when matched
+ */
+
+/**
+ * @typedef {Object} StudioConfig
+ * @property {CustomPattern[]} customPatterns - User-defined page patterns
+ */
+
+/**
+ * Load studio configuration from file
+ * @param {string} configPath - Direct path to config file (optional)
+ * @param {string} projectDir - Project directory to search for config (default: cwd)
+ * @returns {Promise<StudioConfig|null>} Parsed config or null if not found
+ */
+export async function loadConfig(configPath = null, projectDir = process.cwd()) {
+    let targetPath = configPath;
+    
+    // If no direct path, search for config files
+    if (!targetPath) {
+        for (const filename of CONFIG_FILES) {
+            const candidatePath = join(projectDir, filename);
+            if (existsSync(candidatePath)) {
+                targetPath = candidatePath;
+                break;
+            }
+        }
+    }
+    
+    // No config found
+    if (!targetPath || !existsSync(targetPath)) {
+        return null;
+    }
+    
+    try {
+        const content = await readFile(targetPath, 'utf-8');
+        const config = JSON.parse(content);
+        
+        // Validate config
+        const validated = validateConfig(config);
+        
+        return validated;
+    } catch (error) {
+        console.error(`Error loading studio config from ${targetPath}:`, error.message);
+        return null;
+    }
+}
+
+/**
+ * Validate and normalize config structure
+ * @param {Object} config - Raw config object
+ * @returns {StudioConfig} Validated config
+ * @throws {Error} If config is invalid
+ */
+export function validateConfig(config) {
+    if (!config || typeof config !== 'object') {
+        throw new Error('Config must be an object');
+    }
+    
+    const validated = {
+        customPatterns: []
+    };
+    
+    // Validate customPatterns
+    if (config.customPatterns) {
+        if (!Array.isArray(config.customPatterns)) {
+            throw new Error('customPatterns must be an array');
+        }
+        
+        for (let i = 0; i < config.customPatterns.length; i++) {
+            const pattern = config.customPatterns[i];
+            
+            if (!pattern || typeof pattern !== 'object') {
+                throw new Error(`Pattern at index ${i} must be an object`);
+            }
+            
+            if (!Array.isArray(pattern.keywords) || pattern.keywords.length === 0) {
+                throw new Error(`Pattern at index ${i} must have non-empty 'keywords' array`);
+            }
+            
+            if (typeof pattern.type !== 'string' || pattern.type.trim() === '') {
+                throw new Error(`Pattern at index ${i} must have non-empty 'type' string`);
+            }
+            
+            // Normalize keywords to lowercase
+            validated.customPatterns.push({
+                keywords: pattern.keywords.map(k => String(k).toLowerCase().trim()),
+                type: pattern.type.trim()
+            });
+        }
+    }
+    
+    return validated;
+}
+
+/**
+ * Merge custom patterns with default patterns
+ * Custom patterns take priority (checked first)
+ * @param {Array} defaultPatterns - Default page patterns
+ * @param {CustomPattern[]} customPatterns - User-defined patterns
+ * @returns {Array} Merged patterns with custom first
+ */
+export function mergePatterns(defaultPatterns, customPatterns) {
+    if (!customPatterns || customPatterns.length === 0) {
+        return defaultPatterns;
+    }
+    
+    // Convert custom patterns to same format as default patterns
+    const formattedCustom = customPatterns.map(p => ({
+        keywords: p.keywords,
+        type: p.type
+    }));
+    
+    // Custom patterns first (higher priority)
+    return [...formattedCustom, ...defaultPatterns];
+}
+
+/**
+ * Create example config for users
+ * @returns {string} JSON string of example config
+ */
+export function getExampleConfig() {
+    const example = {
+        $schema: 'https://agentskillkit.dev/schemas/studio-config.json',
+        customPatterns: [
+            {
+                keywords: ['inventory', 'warehouse', 'stock', 'shipment'],
+                type: 'Inventory Management'
+            },
+            {
+                keywords: ['calendar', 'scheduling', 'appointment', 'booking'],
+                type: 'Calendar / Scheduling'
+            },
+            {
+                keywords: ['chat', 'messaging', 'conversation', 'inbox'],
+                type: 'Chat / Messaging'
+            }
+        ]
+    };
+    
+    return JSON.stringify(example, null, 2);
+}

package/.agent/skills/studio/scripts-js/utils/css-templates.js

@@ -0,0 +1,168 @@
+/**
+ * CSS Template Generators - Studio Design System
+ * ===============================================
+ * Utilities for generating CSS variables and token systems
+ * Used by formatMasterMd() and formatPageOverrideMd()
+ */
+
+/**
+ * Generate CSS custom properties for color palette
+ * @param {Object} colorData - Color palette data from design system
+ * @returns {string} CSS custom properties block
+ */
+export function generateColorVars(colorData) {
+    if (!colorData) return '';
+
+    const lines = [];
+    lines.push(':root {');
+
+    if (colorData.primary) {
+        lines.push(`  --color-primary: ${colorData.primary};`);
+    }
+    if (colorData.secondary) {
+        lines.push(`  --color-secondary: ${colorData.secondary};`);
+    }
+    if (colorData.cta) {
+        lines.push(`  --color-cta: ${colorData.cta};`);
+    }
+    if (colorData.background) {
+        lines.push(`  --color-bg: ${colorData.background};`);
+    }
+    if (colorData.text) {
+        lines.push(`  --color-text: ${colorData.text};`);
+    }
+    if (colorData.border) {
+        lines.push(`  --color-border: ${colorData.border};`);
+    }
+
+    lines.push('}');
+    return lines.join('\n');
+}
+
+/**
+ * Generate 7-level spacing scale (xs to 3xl)
+ * Based on 4px base unit (common design system standard)
+ * @returns {string} CSS spacing variables
+ */
+export function generateSpacingScale() {
+    const spacings = {
+        'xs': '4px',   // 0.25rem
+        'sm': '8px',   // 0.5rem
+        'md': '16px',  // 1rem
+        'lg': '24px',  // 1.5rem
+        'xl': '32px',  // 2rem
+        '2xl': '48px', // 3rem
+        '3xl': '64px'  // 4rem
+    };
+
+    const lines = [];
+    lines.push(':root {');
+
+    for (const [size, value] of Object.entries(spacings)) {
+        lines.push(`  --spacing-${size}: ${value};`);
+    }
+
+    lines.push('}');
+    lines.push('');
+    lines.push('/* Usage Examples:');
+    lines.push(' * padding: var(--spacing-md);  // 16px');
+    lines.push(' * margin-top: var(--spacing-lg);  // 24px');
+    lines.push(' * gap: var(--spacing-sm);  // 8px');
+    lines.push(' */');
+
+    return lines.join('\n');
+}
+
+/**
+ * Generate 4-level shadow depth system
+ * Based on Material Design elevation principles
+ * @returns {string} CSS shadow variables
+ */
+export function generateShadowDepths() {
+    const shadows = {
+        'sm': '0 1px 2px 0 rgba(0, 0, 0, 0.05)',  // Cards, buttons
+        'md': '0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)',  // Dropdowns
+        'lg': '0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05)',  // Modals
+        'xl': '0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04)'  // Overlays
+    };
+
+    const lines = [];
+    lines.push(':root {');
+
+    for (const [depth, value] of Object.entries(shadows)) {
+        lines.push(`  --shadow-${depth}: ${value};`);
+    }
+
+    lines.push('}');
+    lines.push('');
+    lines.push('/* Usage Examples:');
+    lines.push(' * box-shadow: var(--shadow-sm);  // Subtle card elevation');
+    lines.push(' * box-shadow: var(--shadow-md);  // Dropdown menus');
+    lines.push(' * box-shadow: var(--shadow-lg);  // Modal dialogs');
+    lines.push(' * box-shadow: var(--shadow-xl);  // Full-page overlays');
+    lines.push(' */');
+
+    return lines.join('\n');
+}
+
+/**
+ * Generate border radius scale
+ * @returns {string} CSS border radius variables
+ */
+export function generateBorderRadiusScale() {
+    const radii = {
+        'none': '0',
+        'sm': '0.125rem',  // 2px
+        'md': '0.375rem',  // 6px
+        'lg': '0.5rem',    // 8px
+        'xl': '0.75rem',   // 12px
+        'full': '9999px'   // Fully rounded
+    };
+
+    const lines = [];
+    lines.push(':root {');
+
+    for (const [size, value] of Object.entries(radii)) {
+        lines.push(`  --radius-${size}: ${value};`);
+    }
+
+    lines.push('}');
+
+    return lines.join('\n');
+}
+
+/**
+ * Generate complete CSS token system
+ * Combines all token generators
+ * @param {Object} colorData - Color palette from design system
+ * @returns {string} Complete CSS variables block
+ */
+export function generateTokenSystem(colorData) {
+    const sections = [];
+
+    sections.push('/* === Design Tokens === */');
+    sections.push('');
+
+    // Colors
+    if (colorData && Object.keys(colorData).length > 0) {
+        sections.push('/* Colors */');
+        sections.push(generateColorVars(colorData));
+        sections.push('');
+    }
+
+    // Spacing
+    sections.push('/* Spacing Scale */');
+    sections.push(generateSpacingScale());
+    sections.push('');
+
+    // Shadows
+    sections.push('/* Shadow Depths */');
+    sections.push(generateShadowDepths());
+    sections.push('');
+
+    // Border Radius
+    sections.push('/* Border Radius */');
+    sections.push(generateBorderRadiusScale());
+
+    return sections.join('\n');
+}

package/.agent/skills/studio/scripts-js/utils/css-validator.js

@@ -0,0 +1,94 @@
+/**
+ * CSS Validator - Studio Design System
+ * =====================================
+ * Validates generated CSS syntax using css-tree parser
+ * Non-blocking validation with optional strict mode
+ */
+
+import * as cssTree from 'css-tree';
+
+/**
+ * Validate CSS syntax
+ * @param {string} css - CSS string to validate
+ * @param {Object} options - Validation options
+ * @param {boolean} options.strict - If true, throw error on invalid CSS
+ * @returns {{ valid: boolean, errors: Array<{message: string, line: number, column: number}> }}
+ */
+export function validateCss(css, options = {}) {
+    const { strict = false } = options;
+    const errors = [];
+
+    if (!css || typeof css !== 'string') {
+        return { valid: true, errors: [] }; // Empty/null CSS is valid
+    }
+
+    try {
+        // Parse CSS - cssTree.parse throws on syntax errors
+        cssTree.parse(css, {
+            onParseError: (error) => {
+                errors.push({
+                    message: error.message,
+                    line: error.line || 0,
+                    column: error.column || 0
+                });
+            }
+        });
+    } catch (parseError) {
+        errors.push({
+            message: parseError.message,
+            line: parseError.line || 0,
+            column: parseError.column || 0
+        });
+    }
+
+    const valid = errors.length === 0;
+
+    if (strict && !valid) {
+        throw new Error(`CSS validation failed:\n${errors.map(e => `  Line ${e.line}: ${e.message}`).join('\n')}`);
+    }
+
+    return { valid, errors };
+}
+
+/**
+ * Validate CSS and return formatted result for logging
+ * @param {string} css - CSS string to validate
+ * @param {string} context - Context description for error messages
+ * @returns {string|null} Error message or null if valid
+ */
+export function validateCssWithContext(css, context = 'CSS') {
+    const result = validateCss(css);
+    
+    if (!result.valid) {
+        const errorLines = result.errors.map(e => 
+            `  Line ${e.line}, Col ${e.column}: ${e.message}`
+        ).join('\n');
+        return `⚠️ ${context} validation warnings:\n${errorLines}`;
+    }
+    
+    return null;
+}
+
+/**
+ * Extract CSS blocks from markdown and validate each
+ * @param {string} markdown - Markdown content with CSS code blocks
+ * @returns {{ valid: boolean, warnings: string[] }}
+ */
+export function validateMarkdownCss(markdown) {
+    const cssBlockRegex = /```css\n([\s\S]*?)```/g;
+    const warnings = [];
+    let match;
+
+    while ((match = cssBlockRegex.exec(markdown)) !== null) {
+        const cssContent = match[1].trim();
+        const validation = validateCss(cssContent);
+        
+        if (!validation.valid) {
+            validation.errors.forEach(err => {
+                warnings.push(`CSS block error (line ${err.line}): ${err.message}`);
+            });
+        }
+    }
+
+    return { valid: warnings.length === 0, warnings };
+}

package/.agent/skills/studio/scripts-js/utils/csv-loader.js

@@ -0,0 +1,55 @@
+/**
+ * CSV Loader Utility - Studio Scripts
+ * ====================================
+ * CSV parsing with UTF-8 encoding support
+ * JavaScript port of Python's csv.DictReader
+ */
+
+import { readFile } from 'fs/promises';
+import { parse } from 'csv-parse/sync';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Data directory path (relative to scripts-js/)
+export const DATA_DIR = join(__dirname, '..', '..', 'data');
+
+/**
+ * Load CSV file and return array of objects
+ * @param {string} filepath - Relative path from DATA_DIR
+ * @returns {Promise<Array<Object>>} Array of row objects
+ */
+export async function loadCSV(filepath) {
+    try {
+        const fullPath = join(DATA_DIR, filepath);
+        const content = await readFile(fullPath, 'utf-8');
+
+        const records = parse(content, {
+            columns: true,        // First row as headers
+            skip_empty_lines: true,
+            trim: true,
+            encoding: 'utf-8'
+        });
+
+        return records;
+    } catch (error) {
+        console.error(`Error loading CSV: ${filepath}`, error.message);
+        return [];
+    }
+}
+
+/**
+ * Load CSV and check if file exists
+ * @param {string} filepath - Relative path from DATA_DIR
+ * @returns {Promise<{exists: boolean, data: Array}>}
+ */
+export async function loadCSVSafe(filepath) {
+    try {
+        const data = await loadCSV(filepath);
+        return { exists: true, data };
+    } catch (error) {
+        return { exists: false, data: [] };
+    }
+}

package/.agent/skills/studio/scripts-js/utils/intelligent-overrides.js

@@ -0,0 +1,128 @@
+/**
+ * Intelligent Page Override Generator - Studio Design System
+ * ============================================================
+ * Generates intelligent page-specific overrides using multi-domain search
+ * This is the core logic for Phase 5 - matches Python version exactly
+ */
+
+import { search } from '../core.js';
+import { detectPageType } from './page-type-detector.js';
+
+/**
+ * Generate intelligent overrides based on page type using layered search
+ * @param {string} pageName - Page name (e.g., "dashboard", "checkout")
+ * @param {string} pageQuery - Optional query for context (e.g., "SaaS dashboard")
+ * @param {Object} designSystem - Base design system object
+ * @returns {Promise<Object>} Override object with layout, spacing, typography, colors, components, recommendations
+ */
+export async function generateIntelligentOverrides(pageName, pageQuery, designSystem) {
+    const pageLower = (pageName || '').toLowerCase();
+    const queryLower = (pageQuery || '').toLowerCase();
+    const combinedContext = `${pageLower} ${queryLower}`.trim();
+
+    // Search across multiple domains for page-specific guidance
+    const styleSearch = await search(combinedContext, 'style', 1);
+    const uxSearch = await search(combinedContext, 'ux', 3);
+    const landingSearch = await search(combinedContext, 'landing', 1);
+
+    // Extract results from search response
+    const styleResults = styleSearch?.results || [];
+    const uxResults = uxSearch?.results || [];
+    const landingResults = landingSearch?.results || [];
+
+    // Detect page type from search results or context
+    const pageType = detectPageType(combinedContext, styleResults);
+
+    // Build overrides from search results
+    const layout = {};
+    const spacing = {};
+    const typography = {};
+    const colors = {};
+    const components = [];
+    const uniqueComponents = [];
+    const recommendations = [];
+
+    // Extract style-based overrides
+    if (styleResults.length > 0) {
+        const style = styleResults[0];
+        const styleName = style['Style Category'] || '';
+        const keywords = (style['Keywords'] || '').toLowerCase();
+        const bestFor = style['Best For'] || '';
+        const effects = style['Effects & Animation'] || '';
+
+        // Infer layout from style keywords
+        const dataKeywords = ['data', 'dense', 'dashboard', 'grid'];
+        const minimalKeywords = ['minimal', 'simple', 'clean', 'single'];
+
+        if (dataKeywords.some(kw => keywords.includes(kw))) {
+            layout['Max Width'] = '1400px or full-width';
+            layout['Grid'] = '12-column grid for data flexibility';
+            spacing['Content Density'] = 'High — optimize for information display';
+        } else if (minimalKeywords.some(kw => keywords.includes(kw))) {
+            layout['Max Width'] = '800px (narrow, focused)';
+            layout['Layout'] = 'Single column, centered';
+            spacing['Content Density'] = 'Low — focus on clarity';
+        } else {
+            layout['Max Width'] = '1200px (standard)';
+            layout['Layout'] = 'Full-width sections, centered content';
+        }
+
+        if (effects) {
+            recommendations.push(`Effects: ${effects}`);
+        }
+    }
+
+    // Extract UX guidelines as recommendations
+    for (const ux of uxResults) {
+        const category = ux['Category'] || '';
+        const doText = ux['Do'] || '';
+        const dontText = ux["Don't"] || '';
+
+        if (doText) {
+            recommendations.push(`${category}: ${doText}`);
+        }
+        if (dontText) {
+            components.push(`Avoid: ${dontText}`);
+        }
+    }
+
+    // Extract landing pattern info for section structure
+    if (landingResults.length > 0) {
+        const landing = landingResults[0];
+        const sections = landing['Section Order'] || '';
+        const ctaPlacement = landing['Primary CTA Placement'] || '';
+        const colorStrategy = landing['Color Strategy'] || '';
+
+        if (sections) {
+            layout['Sections'] = sections;
+        }
+        if (ctaPlacement) {
+            recommendations.push(`CTA Placement: ${ctaPlacement}`);
+        }
+        if (colorStrategy) {
+            colors['Strategy'] = colorStrategy;
+        }
+    }
+
+    // Add page-type specific defaults if no search results
+    if (Object.keys(layout).length === 0) {
+        layout['Max Width'] = '1200px';
+        layout['Layout'] = 'Responsive grid';
+    }
+
+    if (recommendations.length === 0) {
+        recommendations.push('Refer to MASTER.md for all design rules');
+        recommendations.push('Add specific overrides as needed for this page');
+    }
+
+    return {
+        page_type: pageType,
+        layout,
+        spacing,
+        typography,
+        colors,
+        components,
+        unique_components: uniqueComponents,
+        recommendations
+    };
+}