@agentskillkit/agent-skills 1.0.1 → 3.2.1

package/.agent/skills/studio/scripts-js/utils/page-override-formatter.js

@@ -0,0 +1,142 @@
+/**
+ * Page Override Formatter - Studio Design System
+ * ================================================
+ * Formats page-specific override markdown files
+ * Final component of Phase 6 - matches Python version exactly
+ */
+
+import { generateIntelligentOverrides } from './intelligent-overrides.js';
+
+/**
+ * Format a page-specific override file with intelligent AI-generated content
+ * @param {Object} designSystem - Base design system object
+ * @param {string} pageName - Page name (e.g., "dashboard", "checkout")
+ * @param {string} pageQuery - Optional query for additional context
+ * @returns {Promise<string>} Formatted markdown content for page override file
+ */
+export async function formatPageOverrideMd(designSystem, pageName, pageQuery = null) {
+    const project = designSystem.project_name || 'PROJECT';
+    const timestamp = new Date().toISOString(); // Full ISO 8601 UTC format
+    const pageTitle = pageName
+        .replace(/-/g, ' ')
+        .replace(/_/g, ' ')
+        .split(' ')
+        .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+
+    // Detect page type and generate intelligent overrides
+    const pageOverrides = await generateIntelligentOverrides(pageName, pageQuery, designSystem);
+
+    const lines = [];
+
+    lines.push(`# ${pageTitle} Page Overrides`);
+    lines.push('');
+    lines.push(`> **PROJECT:** ${project}`);
+    lines.push(`> **Generated:** ${timestamp}`);
+    lines.push(`> **Page Type:** ${pageOverrides.page_type || 'General'}`);
+    lines.push('');
+    lines.push('> ⚠️ **IMPORTANT:** Rules in this file **override** the Master file (`design-system/MASTER.md`).');
+    lines.push('> Only deviations from the Master are documented here. For all other rules, refer to the Master.');
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+
+    // Page-specific rules with actual content
+    lines.push('## Page-Specific Rules');
+    lines.push('');
+
+    // Layout Overrides
+    lines.push('### Layout Overrides');
+    lines.push('');
+    const layout = pageOverrides.layout || {};
+    if (Object.keys(layout).length > 0) {
+        for (const [key, value] of Object.entries(layout)) {
+            lines.push(`- **${key}:** ${value}`);
+        }
+    } else {
+        lines.push('- No overrides — use Master layout');
+    }
+    lines.push('');
+
+    // Spacing Overrides
+    lines.push('### Spacing Overrides');
+    lines.push('');
+    const spacing = pageOverrides.spacing || {};
+    if (Object.keys(spacing).length > 0) {
+        for (const [key, value] of Object.entries(spacing)) {
+            lines.push(`- **${key}:** ${value}`);
+        }
+    } else {
+        lines.push('- No overrides — use Master spacing');
+    }
+    lines.push('');
+
+    // Typography Overrides
+    lines.push('### Typography Overrides');
+    lines.push('');
+    const typography = pageOverrides.typography || {};
+    if (Object.keys(typography).length > 0) {
+        for (const [key, value] of Object.entries(typography)) {
+            lines.push(`- **${key}:** ${value}`);
+        }
+    } else {
+        lines.push('- No overrides — use Master typography');
+    }
+    lines.push('');
+
+    // Color Overrides
+    lines.push('### Color Overrides');
+    lines.push('');
+    const colors = pageOverrides.colors || {};
+    if (Object.keys(colors).length > 0) {
+        for (const [key, value] of Object.entries(colors)) {
+            lines.push(`- **${key}:** ${value}`);
+        }
+    } else {
+        lines.push('- No overrides — use Master colors');
+    }
+    lines.push('');
+
+    // Component Overrides
+    lines.push('### Component Overrides');
+    lines.push('');
+    const components = pageOverrides.components || [];
+    if (components.length > 0) {
+        for (const comp of components) {
+            lines.push(`- ${comp}`);
+        }
+    } else {
+        lines.push('- No overrides — use Master component specs');
+    }
+    lines.push('');
+
+    // Page-Specific Components
+    lines.push('---');
+    lines.push('');
+    lines.push('## Page-Specific Components');
+    lines.push('');
+    const uniqueComponents = pageOverrides.unique_components || [];
+    if (uniqueComponents.length > 0) {
+        for (const comp of uniqueComponents) {
+            lines.push(`- ${comp}`);
+        }
+    } else {
+        lines.push('- No unique components for this page');
+    }
+    lines.push('');
+
+    // Recommendations
+    lines.push('---');
+    lines.push('');
+    lines.push('## Recommendations');
+    lines.push('');
+    const recommendations = pageOverrides.recommendations || [];
+    if (recommendations.length > 0) {
+        for (const rec of recommendations) {
+            lines.push(`- ${rec}`);
+        }
+    }
+    lines.push('');
+
+    return lines.join('\n');
+}

package/.agent/skills/studio/scripts-js/utils/page-type-detector.js

@@ -0,0 +1,123 @@
+/**
+ * Page Type Detection - Studio Design System
+ * ===========================================
+ * Detects page types from context and search results
+ * Used by intelligent override generation (Phase 5)
+ * 
+ * Supports custom patterns via .studiorc.json or studio-config.json
+ */
+
+import { loadConfig, mergePatterns } from './config-loader.js';
+
+/**
+ * Default page type patterns (exported for extension/override)
+ * NOTE: Order matters - more specific patterns should come first
+ */
+export const DEFAULT_PATTERNS = [
+    {
+        keywords: ['dashboard', 'admin', 'analytics', 'data', 'metrics', 'stats', 'monitor', 'overview'],
+        type: 'Dashboard / Data View'
+    },
+    {
+        keywords: ['checkout', 'payment', 'cart', 'purchase', 'order', 'billing'],
+        type: 'Checkout / Payment'
+    },
+    {
+        // IMPORTANT: Don't include 'account' here due to collision with 'register account' (Authentication)
+        keywords: ['settings', 'profile', 'preferences', 'config'],
+        type: 'Settings / Profile'
+    },
+    {
+        keywords: ['landing', 'marketing', 'homepage', 'hero', 'home', 'promo'],
+        type: 'Landing / Marketing'
+    },
+    {
+        // 'account' keyword handled here (for register/create account flows)
+        keywords: ['login', 'signin', 'signup', 'register', 'auth', 'password', 'account'],
+        type: 'Authentication'
+    },
+    {
+        // Added 'package' (singular) to match 'package options'
+        keywords: ['pricing', 'plans', 'subscription', 'tiers', 'packages', 'package'],
+        type: 'Pricing / Plans'
+    },
+    {
+        keywords: ['blog', 'article', 'post', 'news', 'content', 'story'],
+        type: 'Blog / Article'
+    },
+    {
+        keywords: ['product', 'item', 'detail', 'pdp', 'shop', 'store'],
+        type: 'Product Detail'
+    },
+    {
+        keywords: ['search', 'browse', 'filter', 'catalog', 'list'],
+        type: 'Search Results'
+    },
+    {
+        // IMPORTANT: 'results' removed to avoid collision with 'Search Results'
+        // 'zero results' should match on 'zero', not 'results'
+        keywords: ['empty', '404', 'error', 'not found', 'zero'],
+        type: 'Empty State'
+    }
+];
+
+/**
+ * Detect page type from context string and style results
+ * Uses DEFAULT_PATTERNS only (for backward compatibility)
+ * @param {string} context - Combined page name + query context
+ * @param {Array} styleResults - Style search results for fallback inference
+ * @returns {string} Detected page type
+ */
+export function detectPageType(context, styleResults = []) {
+    return detectPageTypeWithPatterns(context, styleResults, DEFAULT_PATTERNS);
+}
+
+/**
+ * Detect page type with custom patterns from config
+ * Loads user config and merges custom patterns (higher priority)
+ * @param {string} context - Combined page name + query context
+ * @param {Array} styleResults - Style search results for fallback inference
+ * @param {string} projectDir - Project directory to search for config
+ * @returns {Promise<string>} Detected page type
+ */
+export async function detectPageTypeWithConfig(context, styleResults = [], projectDir = process.cwd()) {
+    const config = await loadConfig(null, projectDir);
+    const customPatterns = config?.customPatterns || [];
+    const patterns = mergePatterns(DEFAULT_PATTERNS, customPatterns);
+    
+    return detectPageTypeWithPatterns(context, styleResults, patterns);
+}
+
+/**
+ * Core page type detection logic with configurable patterns
+ * @param {string} context - Combined page name + query context
+ * @param {Array} styleResults - Style search results for fallback inference
+ * @param {Array} patterns - Page patterns to match against
+ * @returns {string} Detected page type
+ */
+function detectPageTypeWithPatterns(context, styleResults, patterns) {
+    const contextLower = (context || '').toLowerCase();
+
+    // Check each pattern for keyword matches
+    for (const { keywords, type } of patterns) {
+        if (keywords.some(kw => contextLower.includes(kw))) {
+            return type;
+        }
+    }
+
+    // Fallback: try to infer from style results
+    if (styleResults && styleResults.length > 0) {
+        const styleName = (styleResults[0]['Style Category'] || '').toLowerCase();
+        const bestFor = (styleResults[0]['Best For'] || '').toLowerCase();
+
+        if (bestFor.includes('dashboard') || bestFor.includes('data')) {
+            return 'Dashboard / Data View';
+        } else if (bestFor.includes('landing') || bestFor.includes('marketing')) {
+            return 'Landing / Marketing';
+        }
+    }
+
+    // Final fallback
+    return 'General';
+}
+

package/.agent/skills/studio/scripts-js/utils/search-cache.js

@@ -0,0 +1,190 @@
+/**
+ * Search Results Cache - Studio Design System
+ * =============================================
+ * LRU cache for search results to reduce CSV parsing overhead
+ * Provides 10x faster repeated searches
+ */
+
+/**
+ * Simple LRU (Least Recently Used) Cache implementation
+ * @class
+ */
+class LRUCache {
+    /**
+     * @param {number} maxSize - Maximum number of entries to cache
+     * @param {number} ttlMs - Time to live in milliseconds (default: 5 minutes)
+     */
+    constructor(maxSize = 50, ttlMs = 5 * 60 * 1000) {
+        this.maxSize = maxSize;
+        this.ttlMs = ttlMs;
+        this.cache = new Map();
+    }
+
+    /**
+     * Generate cache key from search parameters
+     * @param {string} query - Search query
+     * @param {string} domain - Search domain (style, ux, landing, etc.)
+     * @param {number} maxResults - Maximum results to return
+     * @returns {string} Cache key
+     */
+    static generateKey(query, domain, maxResults) {
+        const normalizedQuery = (query || '').toLowerCase().trim();
+        return `${normalizedQuery}:${domain}:${maxResults}`;
+    }
+
+    /**
+     * Get value from cache
+     * @param {string} key - Cache key
+     * @returns {*} Cached value or undefined if not found/expired
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        
+        if (!entry) {
+            return undefined;
+        }
+
+        // Check if entry has expired
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return undefined;
+        }
+
+        // Move to end (most recently used)
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+
+        return entry.value;
+    }
+
+    /**
+     * Set value in cache
+     * @param {string} key - Cache key
+     * @param {*} value - Value to cache
+     */
+    set(key, value) {
+        // Delete if exists (to update position)
+        if (this.cache.has(key)) {
+            this.cache.delete(key);
+        }
+
+        // Evict oldest entry if at capacity
+        if (this.cache.size >= this.maxSize) {
+            const oldestKey = this.cache.keys().next().value;
+            this.cache.delete(oldestKey);
+        }
+
+        // Add new entry
+        this.cache.set(key, {
+            value,
+            expiresAt: Date.now() + this.ttlMs,
+            createdAt: Date.now()
+        });
+    }
+
+    /**
+     * Check if key exists and is not expired
+     * @param {string} key - Cache key
+     * @returns {boolean}
+     */
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry) return false;
+        
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return false;
+        }
+        
+        return true;
+    }
+
+    /**
+     * Clear all cache entries
+     */
+    clear() {
+        this.cache.clear();
+    }
+
+    /**
+     * Get current cache size
+     * @returns {number}
+     */
+    get size() {
+        return this.cache.size;
+    }
+
+    /**
+     * Get cache statistics
+     * @returns {{ size: number, maxSize: number, ttlMs: number }}
+     */
+    getStats() {
+        return {
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            ttlMs: this.ttlMs
+        };
+    }
+}
+
+// Global cache instance for search results
+const searchCache = new LRUCache(50, 5 * 60 * 1000); // 50 entries, 5 min TTL
+
+// Cache hit/miss statistics
+let cacheStats = {
+    hits: 0,
+    misses: 0
+};
+
+/**
+ * Wrap a search function with caching
+ * @param {Function} searchFn - Original search function
+ * @param {string} domain - Search domain for cache key
+ * @returns {Function} Cached search function
+ */
+export function withCache(searchFn, domain) {
+    return async function cachedSearch(query, maxResults = 5) {
+        const key = LRUCache.generateKey(query, domain, maxResults);
+        
+        // Check cache first
+        const cachedResult = searchCache.get(key);
+        if (cachedResult !== undefined) {
+            cacheStats.hits++;
+            return cachedResult;
+        }
+        
+        // Cache miss - execute search
+        cacheStats.misses++;
+        const result = await searchFn(query, domain, maxResults);
+        
+        // Store in cache
+        searchCache.set(key, result);
+        
+        return result;
+    };
+}
+
+/**
+ * Clear the search cache
+ */
+export function clearSearchCache() {
+    searchCache.clear();
+    cacheStats = { hits: 0, misses: 0 };
+}
+
+/**
+ * Get cache statistics
+ * @returns {{ hits: number, misses: number, hitRate: number, cacheSize: number }}
+ */
+export function getCacheStats() {
+    const total = cacheStats.hits + cacheStats.misses;
+    return {
+        hits: cacheStats.hits,
+        misses: cacheStats.misses,
+        hitRate: total > 0 ? (cacheStats.hits / total * 100).toFixed(1) + '%' : '0%',
+        cacheSize: searchCache.size
+    };
+}
+
+// Export for testing
+export { LRUCache, searchCache };

package/.agent/skills/studio/scripts-js/utils/text-utils.js

@@ -0,0 +1,54 @@
+/**
+ * Text Utilities - Studio Scripts
+ * ================================
+ * Tokenization helpers for BM25 search
+ * JavaScript port of Python's BM25.tokenize() method
+ */
+
+/**
+ * Tokenize text for BM25 search
+ * Equivalent to Python: re.sub(r'[^\w\s]', ' ', str(text).lower()).split()
+ * @param {string} text - Input text to tokenize
+ * @returns {string[]} Array of tokens (words > 2 chars)
+ */
+export function tokenize(text) {
+    if (!text) return [];
+
+    // Convert to string, lowercase, remove punctuation
+    const cleaned = String(text)
+        .toLowerCase()
+        .replace(/[^\w\s]/g, ' ');  // Remove non-word, non-space chars
+
+    // Split and filter words > 2 characters
+    return cleaned
+        .split(/\s+/)
+        .filter(word => word.length > 2);
+}
+
+/**
+ * Join multiple column values into single searchable document
+ * @param {Object} row - CSV row object
+ * @param {string[]} columns - Columns to join
+ * @returns {string} Joined text
+ */
+export function buildDocument(row, columns) {
+    return columns
+        .map(col => row[col] || '')
+        .join(' ');
+}
+
+/**
+ * Extract subset of columns from row object
+ * @param {Object} row - Source row object
+ * @param {string[]} columns - Columns to extract
+ * @returns {Object} Filtered object with only specified columns
+ */
+export function extractColumns(row, columns) {
+    const result = {};
+    for (const col of columns) {
+        if (col in row) {
+            result[col] = row[col];
+        }
+    }
+    return result;
+}