agent-skill-kit 3.9.135

package/.agent/skills/studio/scripts/search.ts

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+// @ts-nocheck
+/**
+ * Studio Search CLI
+ *
+ * CLI entry point for Studio search and design system generation.
+ * BM25-powered search across 24 CSV databases with design system output.
+ *
+ * @version 2.0.0
+ * @contract studio v2.0.0
+ * @see references/engineering-spec.md
+ */
+
+import { parseArgs } from 'node:util';
+import { search, searchStack, CSV_CONFIG, AVAILABLE_STACKS } from './core.ts';
+import { generateDesignSystem } from './design_system.ts';
+
+/**
+ * Format search results for terminal output
+ */
+function formatOutput(result) {
+    if (result.error) {
+        return `Error: ${result.error}`;
+    }
+
+    const output = [];
+    if (result.stack) {
+        output.push('## Studio Stack Guidelines');
+        output.push(`**Stack:** ${result.stack} | **Query:** ${result.query}`);
+    } else {
+        output.push('## Studio Search Results');
+        output.push(`**Domain:** ${result.domain} | **Query:** ${result.query}`);
+    }
+    output.push(`**Source:** ${result.file} | **Found:** ${result.count} results\n`);
+
+    result.results.forEach((row, i) => {
+        output.push(`### Result ${i + 1}`);
+        for (const [key, value] of Object.entries(row)) {
+            let valueStr = String(value);
+            if (valueStr.length > 300) {
+                valueStr = valueStr.slice(0, 300) + '...';
+            }
+            output.push(`- **${key}:** ${valueStr}`);
+        }
+        output.push('');
+    });
+
+    return output.join('\n');
+}
+
+/**
+ * Main CLI function
+ */
+async function main() {
+    const options = {
+        domain: {
+            type: 'string',
+            short: 'd'
+        },
+        stack: {
+            type: 'string',
+            short: 's'
+        },
+        'max-results': {
+            type: 'string',
+            short: 'n'
+        },
+        json: {
+            type: 'boolean'
+        },
+        'design-system': {
+            type: 'boolean'
+            // No short option (parseArgs requires single char only)
+        },
+        'project-name': {
+            type: 'string',
+            short: 'p'
+        },
+        format: {
+            type: 'string',
+            short: 'f'
+        },
+        persist: {
+            type: 'boolean'
+        },
+        page: {
+            type: 'string'
+        },
+        'output-dir': {
+            type: 'string',
+            short: 'o'
+        }
+    };
+
+    let args;
+    try {
+        args = parseArgs({
+            options,
+            allowPositionals: true
+        });
+    } catch (error) {
+        console.error(`Error parsing arguments: ${error.message}`);
+        console.error('\nUsage: node search.js "<query>" [options]');
+        console.error('  --domain, -d       Search domain (style, color, chart, etc.)');
+        console.error('  --stack, -s        Stack-specific search (html-tailwind, react, etc.)');
+        console.error('  --max-results, -n  Maximum results (default: 3)');
+        console.error('  --json             Output as JSON');
+        console.error('  --design-system    Generate complete design system');
+        console.error('  --project-name, -p Project name for design system');
+        console.error('  --format, -f       Output format (ascii or markdown)');
+        console.error('  --persist          Save design system to files');
+        console.error('  --page             Page-specific override file');
+        console.error('  --output-dir, -o   Output directory');
+        process.exit(1);
+    }
+
+    const query = args.positionals[0];
+    if (!query) {
+        console.error('Error: Query is required');
+        console.error('\nUsage: node search.js "<query>" [options]');
+        process.exit(1);
+    }
+
+    const domain = args.values.domain;
+    const stack = args.values.stack;
+    const maxResults = args.values['max-results'] ? parseInt(args.values['max-results']) : 3;
+    const jsonOutput = args.values.json || false;
+    const designSystem = args.values['design-system'] || false;
+    const projectName = args.values['project-name'] || null;
+    const format = args.values.format || 'ascii';
+    const persist = args.values.persist || false;
+    const page = args.values.page || null;
+    const outputDir = args.values['output-dir'] || null;
+
+    // Design system takes priority
+    if (designSystem) {
+        const result = await generateDesignSystem(
+            query,
+            projectName,
+            format,
+            persist,
+            page,
+            outputDir
+        );
+        console.log(result);
+
+        // Print persistence confirmation
+        if (persist) {
+            const projectSlug = (projectName || query).toLowerCase().replace(/\s+/g, '-');
+            console.log('\n' + '='.repeat(60));
+            console.log(`✅ Design system persisted to design-system/${projectSlug}/`);
+            console.log(`   📄 design-system/${projectSlug}/MASTER.md (Global Source of Truth)`);
+            if (page) {
+                const pageFilename = page.toLowerCase().replace(/\s+/g, '-');
+                console.log(`   📄 design-system/${projectSlug}/pages/${pageFilename}.md (Page Overrides)`);
+            }
+            console.log('');
+            console.log(`📖 Usage: When building a page, check design-system/${projectSlug}/pages/[page].md first.`);
+            console.log(`   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.`);
+            console.log('='.repeat(60));
+        }
+    }
+    // Stack search
+    else if (stack) {
+        if (!AVAILABLE_STACKS.includes(stack)) {
+            console.error(`Error: Unknown stack: ${stack}. Available: ${AVAILABLE_STACKS.join(', ')}`);
+            process.exit(1);
+        }
+
+        const result = await searchStack(query, stack, maxResults);
+        if (jsonOutput) {
+            console.log(JSON.stringify(result, null, 2));
+        } else {
+            console.log(formatOutput(result));
+        }
+    }
+    // Domain search
+    else {
+        if (domain && !CSV_CONFIG[domain]) {
+            console.error(`Error: Unknown domain: ${domain}. Available: ${Object.keys(CSV_CONFIG).join(', ')}`);
+            process.exit(1);
+        }
+
+        const result = await search(query, domain, maxResults);
+        if (jsonOutput) {
+            console.log(JSON.stringify(result, null, 2));
+        } else {
+            console.log(formatOutput(result));
+        }
+    }
+}
+
+// Run CLI
+main().catch(error => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/.agent/skills/studio/scripts/types.ts

@@ -0,0 +1,147 @@
+/**
+ * Studio Design System - Type Definitions
+ * ===================================================
+ * Proper TypeScript interfaces replacing JSDoc typedefs
+ */
+
+// ============ Core Types ============
+
+export interface CSVConfig {
+    file: string;
+    search_cols: string[];
+    output_cols: string[];
+}
+
+export interface SearchResult {
+    domain: string;
+    query: string;
+    file: string;
+    count: number;
+    results: Record<string, string>[];
+    cached?: boolean;
+    error?: string;
+}
+
+export interface StackSearchResult {
+    domain: string;
+    query: string;
+    file: string;
+    count: number;
+    results: Record<string, string>[];
+    stack: string;
+    error?: string;
+}
+
+export interface SearchOptions {
+    useCache?: boolean;
+}
+
+// ============ Design System Types ============
+
+export interface ColorPalette {
+    primary?: string;
+    secondary?: string;
+    cta?: string;
+    background?: string;
+    text?: string;
+    border?: string;
+}
+
+export interface Typography {
+    'Font Family'?: string;
+    'Body Size'?: string;
+    'Heading Sizes'?: string;
+}
+
+export interface DesignSystem {
+    project_name: string;
+    style?: Record<string, string>;
+    colors?: ColorPalette;
+    typography?: Typography;
+    pattern?: Record<string, string>;
+    key_effects?: string;
+    anti_patterns?: string;
+}
+
+export interface PageOverrides {
+    layout?: { type: string; recommendation: string };
+    spacing?: { approach: string };
+    typography?: Record<string, string>;
+    colors?: Record<string, string>;
+    components?: Record<string, unknown>;
+}
+
+// ============ Cache Types ============
+
+export interface CacheEntry<T = unknown> {
+    value: T;
+    expiresAt: number;
+    createdAt: number;
+}
+
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    hitRate: string;
+    cacheSize: number;
+}
+
+export interface LRUCacheConfig {
+    maxSize: number;
+    ttlMs: number;
+}
+
+// ============ Config Types ============
+
+export interface CustomPattern {
+    keywords: string[];
+    type: string;
+}
+
+export interface StudioConfig {
+    $schema?: string;
+    customPatterns?: CustomPattern[];
+}
+
+// ============ CSS Validation Types ============
+
+export interface CSSValidationError {
+    message: string;
+    line: number;
+    column: number;
+}
+
+export interface CSSValidationResult {
+    valid: boolean;
+    errors: CSSValidationError[];
+}
+
+export interface CSSValidationOptions {
+    strict?: boolean;
+}
+
+export interface MarkdownCSSValidation {
+    valid: boolean;
+    warnings: string[];
+}
+
+// ============ Page Type Detection ============
+
+export interface PagePattern {
+    keywords: string[];
+    type: string;
+}
+
+export type PageType =
+    | 'Dashboard / Data View'
+    | 'Checkout / Payment'
+    | 'Settings / Profile'
+    | 'Landing / Marketing'
+    | 'Authentication'
+    | 'Pricing / Plans'
+    | 'Blog / Article'
+    | 'Product Detail'
+    | 'Search Results'
+    | 'Empty State'
+    | 'General'
+    | string;

package/.agent/skills/studio/scripts/utils/component-specs.ts

@@ -0,0 +1,154 @@
+// @ts-nocheck
+/**
+ * Component Spec Generators - Studio Design System
+ * =================================================
+ * Generators for production-ready component CSS specifications
+ * Used by formatMasterMd() to create complete design system files
+ */
+
+/**
+ * Generate button component specifications
+ * @param {Object} colors - Color palette from design system
+ * @returns {string} Button CSS specifications
+ */
+export function generateButtonSpecs(colors) {
+    const primaryColor = colors?.cta || '#F97316';
+    const secondaryColor = colors?.primary || '#2563EB';
+
+    return `### Buttons
+
+\`\`\`css
+/* Primary Button */
+.btn-primary {
+  background: ${primaryColor};
+  color: white;
+  padding: 12px 24px;
+  border-radius: 8px;
+  font-weight: 600;
+  transition: all 200ms ease;
+  cursor: pointer;
+}
+
+.btn-primary:hover {
+  opacity: 0.9;
+  transform: translateY(-1px);
+}
+
+/* Secondary Button */
+.btn-secondary {
+  background: transparent;
+  color: ${secondaryColor};
+  border: 2px solid ${secondaryColor};
+  padding: 12px 24px;
+  border-radius: 8px;
+  font-weight: 600;
+  transition: all 200ms ease;
+  cursor: pointer;
+}
+\`\`\`
+`;
+}
+
+/**
+ * Generate card component specifications
+ * @param {Object} colors - Color palette from design system
+ * @returns {string} Card CSS specifications
+ */
+export function generateCardSpecs(colors) {
+    const bgColor = colors?.background || '#FFFFFF';
+
+    return `### Cards
+
+\`\`\`css
+.card {
+  background: ${bgColor};
+  border-radius: 12px;
+  padding: 24px;
+  box-shadow: var(--shadow-md);
+  transition: all 200ms ease;
+  cursor: pointer;
+}
+
+.card:hover {
+  box-shadow: var(--shadow-lg);
+  transform: translateY(-2px);
+}
+\`\`\`
+`;
+}
+
+/**
+ * Generate input component specifications
+ * @param {Object} colors - Color palette from design system
+ * @returns {string} Input CSS specifications
+ */
+export function generateInputSpecs(colors) {
+    const primaryColor = colors?.primary || '#2563EB';
+
+    return `### Inputs
+
+\`\`\`css
+.input {
+  padding: 12px 16px;
+  border: 1px solid #E2E8F0;
+  border-radius: 8px;
+  font-size: 16px;
+  transition: border-color 200ms ease;
+}
+
+.input:focus {
+  border-color: ${primaryColor};
+  outline: none;
+  box-shadow: 0 0 0 3px ${primaryColor}20;
+}
+\`\`\`
+`;
+}
+
+/**
+ * Generate modal component specifications
+ * @returns {string} Modal CSS specifications
+ */
+export function generateModalSpecs() {
+    return `### Modals
+
+\`\`\`css
+.modal-overlay {
+  background: rgba(0, 0, 0, 0.5);
+  backdrop-filter: blur(4px);
+}
+
+.modal {
+  background: white;
+  border-radius: 16px;
+  padding: 32px;
+  box-shadow: var(--shadow-xl);
+  max-width: 500px;
+  width: 90%;
+}
+\`\`\`
+`;
+}
+
+/**
+ * Generate all component specifications
+ * @param {Object} colors - Color palette from design system
+ * @returns {string} Complete component specs section
+ */
+export function generateComponentSpecs(colors) {
+    const sections = [];
+
+    sections.push('---');
+    sections.push('');
+    sections.push('## Component Specs');
+    sections.push('');
+    sections.push(generateButtonSpecs(colors));
+    sections.push('');
+    sections.push(generateCardSpecs(colors));
+    sections.push('');
+    sections.push(generateInputSpecs(colors));
+    sections.push('');
+    sections.push(generateModalSpecs());
+
+    return sections.join('\n');
+}

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

@@ -0,0 +1,165 @@
+// @ts-nocheck
+/**
+ * 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://pikakit.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);
+}