@agentskillkit/agent-skills 1.0.1 → 3.2.2

package/.agent/skills/studio/scripts-js/jsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "allowJs": true,
+    "checkJs": false,
+    "noEmit": true,
+    "strict": false,
+    "skipLibCheck": true,
+    "declaration": false,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "baseUrl": ".",
+    "paths": {
+      "@studio/*": ["./*"]
+    }
+  },
+  "include": [
+    "*.js",
+    "utils/*.js",
+    "types.d.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

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

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * Studio Search CLI - JavaScript port of search.py
+ * ==================================================
+ * CLI for Studio search and design system generation
+ */
+
+import { parseArgs } from 'node:util';
+import { search, searchStack, CSV_CONFIG, AVAILABLE_STACKS } from './core.js';
+import { generateDesignSystem } from './design_system.js';
+
+/**
+ * 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-js/types.d.ts

@@ -0,0 +1,276 @@
+/**
+ * Studio Design System - TypeScript Type Definitions
+ * ===================================================
+ * Type definitions for the Studio JavaScript library
+ * Provides IDE intellisense without requiring TypeScript compilation
+ */
+
+// ============ Core Types ============
+
+/** CSV column configuration */
+export interface CSVConfig {
+    file: string;
+    search_cols: string[];
+    output_cols: string[];
+}
+
+/** Search result from BM25 query */
+export interface SearchResult {
+    domain: string;
+    query: string;
+    file: string;
+    count: number;
+    results: Record<string, any>[];
+    cached?: boolean;
+}
+
+/** Stack search result */
+export interface StackSearchResult extends SearchResult {
+    stack: string;
+}
+
+/** Search options */
+export interface SearchOptions {
+    useCache?: boolean;
+}
+
+// ============ Design System Types ============
+
+/** Color palette definition */
+export interface ColorPalette {
+    primary?: string;
+    secondary?: string;
+    cta?: string;
+    background?: string;
+    text?: string;
+    border?: string;
+}
+
+/** Typography settings */
+export interface Typography {
+    'Font Family'?: string;
+    'Body Size'?: string;
+    'Heading Sizes'?: string;
+}
+
+/** Complete design system */
+export interface DesignSystem {
+    project_name: string;
+    style?: Record<string, any>;
+    colors?: ColorPalette;
+    typography?: Typography;
+    pattern?: Record<string, any>;
+    key_effects?: string;
+    anti_patterns?: string;
+}
+
+/** Page override settings */
+export interface PageOverrides {
+    layout?: { type: string; recommendation: string };
+    spacing?: { approach: string };
+    typography?: Record<string, any>;
+    colors?: Record<string, any>;
+    components?: Record<string, any>;
+}
+
+// ============ Cache Types ============
+
+/** Cache entry with TTL */
+export interface CacheEntry<T> {
+    value: T;
+    expiresAt: number;
+    createdAt: number;
+}
+
+/** Cache statistics */
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    hitRate: string;
+    cacheSize: number;
+}
+
+/** LRU Cache configuration */
+export interface LRUCacheConfig {
+    maxSize: number;
+    ttlMs: number;
+}
+
+// ============ Config Types ============
+
+/** Custom page pattern */
+export interface CustomPattern {
+    keywords: string[];
+    type: string;
+}
+
+/** Studio configuration file */
+export interface StudioConfig {
+    $schema?: string;
+    customPatterns?: CustomPattern[];
+}
+
+// ============ CSS Validation Types ============
+
+/** CSS validation error */
+export interface CSSValidationError {
+    message: string;
+    line: number;
+    column: number;
+}
+
+/** CSS validation result */
+export interface CSSValidationResult {
+    valid: boolean;
+    errors: CSSValidationError[];
+}
+
+/** CSS validation options */
+export interface CSSValidationOptions {
+    strict?: boolean;
+}
+
+/** Markdown CSS validation */
+export interface MarkdownCSSValidation {
+    valid: boolean;
+    warnings: string[];
+}
+
+// ============ Page Type Detection ============
+
+/** Page type pattern */
+export interface PagePattern {
+    keywords: string[];
+    type: string;
+}
+
+/** Page type enum */
+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; // Custom types from config
+
+// ============ Function Signatures ============
+
+/** Core search function */
+export function search(
+    query: string,
+    domain?: string | null,
+    maxResults?: number,
+    options?: SearchOptions
+): Promise<SearchResult>;
+
+/** Domain detection */
+export function detectDomain(query: string): string;
+
+/** Stack search */
+export function searchStack(
+    query: string,
+    stack?: string,
+    maxResults?: number
+): Promise<StackSearchResult>;
+
+/** Design system generation */
+export function generateDesignSystem(
+    query: string,
+    projectName: string,
+    format?: 'json' | 'yaml' | 'markdown'
+): Promise<string>;
+
+/** Master file formatting */
+export function formatMasterMd(designSystem: DesignSystem): string;
+
+/** Page override formatting */
+export function formatPageOverrideMd(
+    designSystem: DesignSystem,
+    pageName: string,
+    pageQuery?: string | null
+): Promise<string>;
+
+/** Design system persistence */
+export function persistDesignSystem(
+    designSystem: DesignSystem,
+    outputDir: string,
+    page?: string | null,
+    pageQuery?: string | null
+): Promise<string[]>;
+
+/** Page type detection */
+export function detectPageType(
+    context: string,
+    styleResults?: Record<string, any>[]
+): PageType;
+
+/** Config-aware page detection */
+export function detectPageTypeWithConfig(
+    context: string,
+    styleResults?: Record<string, any>[],
+    projectDir?: string
+): Promise<PageType>;
+
+/** Config loading */
+export function loadConfig(
+    configPath?: string | null,
+    projectDir?: string
+): Promise<StudioConfig | null>;
+
+/** Config validation */
+export function validateConfig(config: unknown): StudioConfig;
+
+/** Pattern merging */
+export function mergePatterns(
+    defaultPatterns: PagePattern[],
+    customPatterns: CustomPattern[]
+): PagePattern[];
+
+/** CSS validation */
+export function validateCss(
+    css: string,
+    options?: CSSValidationOptions
+): CSSValidationResult;
+
+/** CSS validation with context */
+export function validateCssWithContext(
+    css: string,
+    context?: string
+): string | null;
+
+/** Markdown CSS validation */
+export function validateMarkdownCss(markdown: string): MarkdownCSSValidation;
+
+/** Cache wrapper */
+export function withCache<T>(
+    searchFn: (query: string, domain: string, maxResults: number) => Promise<T>,
+    domain: string
+): (query: string, maxResults?: number) => Promise<T>;
+
+/** Clear search cache */
+export function clearSearchCache(): void;
+
+/** Get cache statistics */
+export function getCacheStats(): CacheStats;
+
+// ============ LRU Cache Class ============
+
+export declare class LRUCache<T = any> {
+    constructor(maxSize?: number, ttlMs?: number);
+    
+    static generateKey(query: string, domain: string, maxResults: number): string;
+    
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    has(key: string): boolean;
+    clear(): void;
+    
+    readonly size: number;
+    getStats(): { size: number; maxSize: number; ttlMs: number };
+}

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

@@ -0,0 +1,153 @@
+/**
+ * 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');
+}