cokit-cli 1.0.1 → 1.0.2

package/skills/ck-ui-ux-pro-max/scripts/core.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Pro Max Core - BM25 search engine for UI/UX style guides
+"""
+
+import csv
+import re
+from pathlib import Path
+from math import log
+from collections import defaultdict
+
+# ============ CONFIGURATION ============
+DATA_DIR = Path(__file__).parent.parent / "data"
+MAX_RESULTS = 3
+
+CSV_CONFIG = {
+    "style": {
+        "file": "styles.csv",
+        "search_cols": ["Style Category", "Keywords", "Best For", "Type"],
+        "output_cols": ["Style Category", "Type", "Keywords", "Primary Colors", "Effects & Animation", "Best For", "Performance", "Accessibility", "Framework Compatibility", "Complexity"]
+    },
+    "prompt": {
+        "file": "prompts.csv",
+        "search_cols": ["Style Category", "AI Prompt Keywords (Copy-Paste Ready)", "CSS/Technical Keywords"],
+        "output_cols": ["Style Category", "AI Prompt Keywords (Copy-Paste Ready)", "CSS/Technical Keywords", "Implementation Checklist"]
+    },
+    "color": {
+        "file": "colors.csv",
+        "search_cols": ["Product Type", "Keywords", "Notes"],
+        "output_cols": ["Product Type", "Keywords", "Primary (Hex)", "Secondary (Hex)", "CTA (Hex)", "Background (Hex)", "Text (Hex)", "Border (Hex)", "Notes"]
+    },
+    "chart": {
+        "file": "charts.csv",
+        "search_cols": ["Data Type", "Keywords", "Best Chart Type", "Accessibility Notes"],
+        "output_cols": ["Data Type", "Keywords", "Best Chart Type", "Secondary Options", "Color Guidance", "Accessibility Notes", "Library Recommendation", "Interactive Level"]
+    },
+    "landing": {
+        "file": "landing.csv",
+        "search_cols": ["Pattern Name", "Keywords", "Conversion Optimization", "Section Order"],
+        "output_cols": ["Pattern Name", "Keywords", "Section Order", "Primary CTA Placement", "Color Strategy", "Conversion Optimization"]
+    },
+    "product": {
+        "file": "products.csv",
+        "search_cols": ["Product Type", "Keywords", "Primary Style Recommendation", "Key Considerations"],
+        "output_cols": ["Product Type", "Keywords", "Primary Style Recommendation", "Secondary Styles", "Landing Page Pattern", "Dashboard Style (if applicable)", "Color Palette Focus"]
+    },
+    "ux": {
+        "file": "ux-guidelines.csv",
+        "search_cols": ["Category", "Issue", "Description", "Platform"],
+        "output_cols": ["Category", "Issue", "Platform", "Description", "Do", "Don't", "Code Example Good", "Code Example Bad", "Severity"]
+    },
+    "typography": {
+        "file": "typography.csv",
+        "search_cols": ["Font Pairing Name", "Category", "Mood/Style Keywords", "Best For", "Heading Font", "Body Font"],
+        "output_cols": ["Font Pairing Name", "Category", "Heading Font", "Body Font", "Mood/Style Keywords", "Best For", "Google Fonts URL", "CSS Import", "Tailwind Config", "Notes"]
+    }
+}
+
+STACK_CONFIG = {
+    "html-tailwind": {"file": "stacks/html-tailwind.csv"},
+    "react": {"file": "stacks/react.csv"},
+    "nextjs": {"file": "stacks/nextjs.csv"},
+    "vue": {"file": "stacks/vue.csv"},
+    "svelte": {"file": "stacks/svelte.csv"},
+    "swiftui": {"file": "stacks/swiftui.csv"},
+    "react-native": {"file": "stacks/react-native.csv"},
+    "flutter": {"file": "stacks/flutter.csv"}
+}
+
+# Common columns for all stacks
+_STACK_COLS = {
+    "search_cols": ["Category", "Guideline", "Description", "Do", "Don't"],
+    "output_cols": ["Category", "Guideline", "Description", "Do", "Don't", "Code Good", "Code Bad", "Severity", "Docs URL"]
+}
+
+AVAILABLE_STACKS = list(STACK_CONFIG.keys())
+
+
+# ============ BM25 IMPLEMENTATION ============
+class BM25:
+    """BM25 ranking algorithm for text search"""
+
+    def __init__(self, k1=1.5, b=0.75):
+        self.k1 = k1
+        self.b = b
+        self.corpus = []
+        self.doc_lengths = []
+        self.avgdl = 0
+        self.idf = {}
+        self.doc_freqs = defaultdict(int)
+        self.N = 0
+
+    def tokenize(self, text):
+        """Lowercase, split, remove punctuation, filter short words"""
+        text = re.sub(r'[^\w\s]', ' ', str(text).lower())
+        return [w for w in text.split() if len(w) > 2]
+
+    def fit(self, documents):
+        """Build BM25 index from documents"""
+        self.corpus = [self.tokenize(doc) for doc in documents]
+        self.N = len(self.corpus)
+        if self.N == 0:
+            return
+        self.doc_lengths = [len(doc) for doc in self.corpus]
+        self.avgdl = sum(self.doc_lengths) / self.N
+
+        for doc in self.corpus:
+            seen = set()
+            for word in doc:
+                if word not in seen:
+                    self.doc_freqs[word] += 1
+                    seen.add(word)
+
+        for word, freq in self.doc_freqs.items():
+            self.idf[word] = log((self.N - freq + 0.5) / (freq + 0.5) + 1)
+
+    def score(self, query):
+        """Score all documents against query"""
+        query_tokens = self.tokenize(query)
+        scores = []
+
+        for idx, doc in enumerate(self.corpus):
+            score = 0
+            doc_len = self.doc_lengths[idx]
+            term_freqs = defaultdict(int)
+            for word in doc:
+                term_freqs[word] += 1
+
+            for token in query_tokens:
+                if token in self.idf:
+                    tf = term_freqs[token]
+                    idf = self.idf[token]
+                    numerator = tf * (self.k1 + 1)
+                    denominator = tf + self.k1 * (1 - self.b + self.b * doc_len / self.avgdl)
+                    score += idf * numerator / denominator
+
+            scores.append((idx, score))
+
+        return sorted(scores, key=lambda x: x[1], reverse=True)
+
+
+# ============ SEARCH FUNCTIONS ============
+def _load_csv(filepath):
+    """Load CSV and return list of dicts"""
+    with open(filepath, 'r', encoding='utf-8') as f:
+        return list(csv.DictReader(f))
+
+
+def _search_csv(filepath, search_cols, output_cols, query, max_results):
+    """Core search function using BM25"""
+    if not filepath.exists():
+        return []
+
+    data = _load_csv(filepath)
+
+    # Build documents from search columns
+    documents = [" ".join(str(row.get(col, "")) for col in search_cols) for row in data]
+
+    # BM25 search
+    bm25 = BM25()
+    bm25.fit(documents)
+    ranked = bm25.score(query)
+
+    # Get top results with score > 0
+    results = []
+    for idx, score in ranked[:max_results]:
+        if score > 0:
+            row = data[idx]
+            results.append({col: row.get(col, "") for col in output_cols if col in row})
+
+    return results
+
+
+def detect_domain(query):
+    """Auto-detect the most relevant domain from query"""
+    query_lower = query.lower()
+
+    domain_keywords = {
+        "color": ["color", "palette", "hex", "#", "rgb"],
+        "chart": ["chart", "graph", "visualization", "trend", "bar", "pie", "scatter", "heatmap", "funnel"],
+        "landing": ["landing", "page", "cta", "conversion", "hero", "testimonial", "pricing", "section"],
+        "product": ["saas", "ecommerce", "e-commerce", "fintech", "healthcare", "gaming", "portfolio", "crypto", "dashboard"],
+        "prompt": ["prompt", "css", "implementation", "variable", "checklist", "tailwind"],
+        "style": ["style", "design", "ui", "minimalism", "glassmorphism", "neumorphism", "brutalism", "dark mode", "flat", "aurora"],
+        "ux": ["ux", "usability", "accessibility", "wcag", "touch", "scroll", "animation", "keyboard", "navigation", "mobile"],
+        "typography": ["font", "typography", "heading", "serif", "sans"]
+    }
+
+    scores = {domain: sum(1 for kw in keywords if kw in query_lower) for domain, keywords in domain_keywords.items()}
+    best = max(scores, key=scores.get)
+    return best if scores[best] > 0 else "style"
+
+
+def search(query, domain=None, max_results=MAX_RESULTS):
+    """Main search function with auto-domain detection"""
+    if domain is None:
+        domain = detect_domain(query)
+
+    config = CSV_CONFIG.get(domain, CSV_CONFIG["style"])
+    filepath = DATA_DIR / config["file"]
+
+    if not filepath.exists():
+        return {"error": f"File not found: {filepath}", "domain": domain}
+
+    results = _search_csv(filepath, config["search_cols"], config["output_cols"], query, max_results)
+
+    return {
+        "domain": domain,
+        "query": query,
+        "file": config["file"],
+        "count": len(results),
+        "results": results
+    }
+
+
+def search_stack(query, stack, max_results=MAX_RESULTS):
+    """Search stack-specific guidelines"""
+    if stack not in STACK_CONFIG:
+        return {"error": f"Unknown stack: {stack}. Available: {', '.join(AVAILABLE_STACKS)}"}
+
+    filepath = DATA_DIR / STACK_CONFIG[stack]["file"]
+
+    if not filepath.exists():
+        return {"error": f"Stack file not found: {filepath}", "stack": stack}
+
+    results = _search_csv(filepath, _STACK_COLS["search_cols"], _STACK_COLS["output_cols"], query, max_results)
+
+    return {
+        "domain": "stack",
+        "stack": stack,
+        "query": query,
+        "file": STACK_CONFIG[stack]["file"],
+        "count": len(results),
+        "results": results
+    }

package/skills/ck-ui-ux-pro-max/scripts/search.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Pro Max Search - BM25 search engine for UI/UX style guides
+Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--max-results 3]
+
+Domains: style, prompt, color, chart, landing, product, ux, typography
+Stacks: html-tailwind, react, nextjs
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+# Add shared scripts to path for win_compat
+sys.path.insert(0, str(Path.home() / '.claude' / 'scripts'))
+try:
+    from win_compat import ensure_utf8_stdout
+    ensure_utf8_stdout()
+except ImportError:
+    # Fallback if shared utility not available
+    if sys.platform == 'win32':
+        import io
+        if hasattr(sys.stdout, 'buffer'):
+            sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+
+from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, search_stack
+
+
+def format_output(result):
+    """Format results for Claude consumption (token-optimized)"""
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    if result.get("stack"):
+        output.append(f"## UI Pro Max Stack Guidelines")
+        output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}")
+    else:
+        output.append(f"## UI Pro Max Search Results")
+        output.append(f"**Domain:** {result['domain']} | **Query:** {result['query']}")
+    output.append(f"**Source:** {result['file']} | **Found:** {result['count']} results\n")
+
+    for i, row in enumerate(result['results'], 1):
+        output.append(f"### Result {i}")
+        for key, value in row.items():
+            value_str = str(value)
+            if len(value_str) > 300:
+                value_str = value_str[:300] + "..."
+            output.append(f"- **{key}:** {value_str}")
+        output.append("")
+
+    return "\n".join(output)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="UI Pro Max Search")
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", choices=list(CSV_CONFIG.keys()), help="Search domain")
+    parser.add_argument("--stack", "-s", choices=AVAILABLE_STACKS, help="Stack-specific search (html-tailwind, react, nextjs)")
+    parser.add_argument("--max-results", "-n", type=int, default=MAX_RESULTS, help="Max results (default: 3)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+
+    args = parser.parse_args()
+
+    # Stack search takes priority
+    if args.stack:
+        result = search_stack(args.query, args.stack, args.max_results)
+    else:
+        result = search(args.query, args.domain, args.max_results)
+
+    if args.json:
+        import json
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        print(format_output(result))

package/skills/ck-web-frameworks/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: 'ck-web-frameworks'
+description: 'Build modern full-stack web applications with Next.js (App Router, Server Components, RSC, PPR, SSR, SSG, ISR), Turborepo (monorepo management, task pipelines, remote caching, parallel execution), and RemixIcon (3100+ SVG icons in outlined/filled styles). Use when creating React applications, implementing server-side rendering, setting up monorepos with multiple packages, optimizing build performance and caching strategies, adding icon libraries, managing shared dependencies, or working with TypeScript full-stack projects.'
+---
+
+# Web Frameworks Skill Group
+
+Comprehensive guide for building modern full-stack web applications using Next.js, Turborepo, and RemixIcon.
+
+## Overview
+
+This skill group combines three powerful tools for web development:
+
+**Next.js** - React framework with SSR, SSG, RSC, and optimization features
+**Turborepo** - High-performance monorepo build system for JavaScript/TypeScript
+**RemixIcon** - Icon library with 3,100+ outlined and filled style icons
+
+## When to Use This Skill Group
+
+- Building new full-stack web applications with modern React
+- Setting up monorepos with multiple apps and shared packages
+- Implementing server-side rendering and static generation
+- Optimizing build performance with intelligent caching
+- Creating consistent UI with professional iconography
+- Managing workspace dependencies across multiple projects
+- Deploying production-ready applications with proper optimization
+
+## Stack Selection Guide
+
+### Single Application: Next.js + RemixIcon
+
+Use when building a standalone application:
+- E-commerce sites
+- Marketing websites
+- SaaS applications
+- Documentation sites
+- Blogs and content platforms
+
+**Setup:**
+```bash
+npx create-next-app@latest my-app
+cd my-app
+npm install remixicon
+```
+
+### Monorepo: Next.js + Turborepo + RemixIcon
+
+Use when building multiple applications with shared code:
+- Microfrontends
+- Multi-tenant platforms
+- Internal tools with shared component library
+- Multiple apps (web, admin, mobile-web) sharing logic
+- Design system with documentation site
+
+**Setup:**
+```bash
+npx create-turbo@latest my-monorepo
+# Then configure Next.js apps in apps/ directory
+# Install remixicon in shared UI packages
+```
+
+### Framework Features Comparison
+
+| Feature | Next.js | Turborepo | RemixIcon |
+|---------|---------|-----------|-----------|
+| Primary Use | Web framework | Build system | UI icons |
+| Best For | SSR/SSG apps | Monorepos | Consistent iconography |
+| Performance | Built-in optimization | Caching & parallel tasks | Lightweight fonts/SVG |
+| TypeScript | Full support | Full support | Type definitions available |
+
+## Quick Start
+
+### Next.js Application
+
+```bash
+# Create new project
+npx create-next-app@latest my-app
+cd my-app
+
+# Install RemixIcon
+npm install remixicon
+
+# Import in layout
+# app/layout.tsx
+import 'remixicon/fonts/remixicon.css'
+
+# Start development
+npm run dev
+```
+
+### Turborepo Monorepo
+
+```bash
+# Create monorepo
+npx create-turbo@latest my-monorepo
+cd my-monorepo
+
+# Structure:
+# apps/web/          - Next.js application
+# apps/docs/         - Documentation site
+# packages/ui/       - Shared components with RemixIcon
+# packages/config/   - Shared configs
+# turbo.json         - Pipeline configuration
+
+# Run all apps
+npm run dev
+
+# Build all packages
+npm run build
+```
+
+### RemixIcon Integration
+
+```tsx
+// Webfont (HTML/CSS)
+<i className="ri-home-line"></i>
+<i className="ri-search-fill ri-2x"></i>
+
+// React component
+import { RiHomeLine, RiSearchFill } from "@remixicon/react"
+<RiHomeLine size={24} />
+<RiSearchFill size={32} color="blue" />
+```
+
+## Reference Navigation
+
+**Next.js References:**
+- [App Router Architecture](./references/nextjs-app-router.md) - Routing, layouts, pages, parallel routes
+- [Server Components](./references/nextjs-server-components.md) - RSC patterns, client vs server, streaming
+- [Data Fetching](./references/nextjs-data-fetching.md) - fetch API, caching, revalidation, loading states
+- [Optimization](./references/nextjs-optimization.md) - Images, fonts, scripts, bundle analysis, PPR
+
+**Turborepo References:**
+- [Setup & Configuration](./references/turborepo-setup.md) - Installation, workspace config, package structure
+- [Task Pipelines](./references/turborepo-pipelines.md) - Dependencies, parallel execution, task ordering
+- [Caching Strategies](./references/turborepo-caching.md) - Local cache, remote cache, cache invalidation
+
+**RemixIcon References:**
+- [Integration Guide](./references/remix-icon-integration.md) - Installation, usage, customization, accessibility
+
+## Common Patterns & Workflows
+
+### Pattern 1: Full-Stack Monorepo
+
+```
+my-monorepo/
+├── apps/
+│   ├── web/              # Customer-facing Next.js app
+│   ├── admin/            # Admin dashboard Next.js app
+│   └── docs/             # Documentation site
+├── packages/
+│   ├── ui/               # Shared UI with RemixIcon
+│   ├── api-client/       # API client library
+│   ├── config/           # ESLint, TypeScript configs
+│   └── types/            # Shared TypeScript types
+└── turbo.json            # Build pipeline
+```
+
+**turbo.json:**
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "pipeline": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": [".next/**", "!.next/cache/**", "dist/**"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    },
+    "lint": {},
+    "test": {
+      "dependsOn": ["build"]
+    }
+  }
+}
+```
+
+### Pattern 2: Shared Component Library
+
+```tsx
+// packages/ui/src/button.tsx
+import { RiLoader4Line } from "@remixicon/react"
+
+export function Button({ children, loading, icon }) {
+  return (
+    <button>
+      {loading ? <RiLoader4Line className="animate-spin" /> : icon}
+      {children}
+    </button>
+  )
+}
+
+// apps/web/app/page.tsx
+import { Button } from "@repo/ui/button"
+import { RiHomeLine } from "@remixicon/react"
+
+export default function Page() {
+  return <Button icon={<RiHomeLine />}>Home</Button>
+}
+```
+
+### Pattern 3: Optimized Data Fetching
+
+```tsx
+// app/posts/[slug]/page.tsx
+import { notFound } from 'next/navigation'
+
+// Static generation at build time
+export async function generateStaticParams() {
+  const posts = await getPosts()
+  return posts.map(post => ({ slug: post.slug }))
+}
+
+// Revalidate every hour
+async function getPost(slug: string) {
+  const res = await fetch(`https://api.example.com/posts/${slug}`, {
+    next: { revalidate: 3600 }
+  })
+  if (!res.ok) return null
+  return res.json()
+}
+
+export default async function Post({ params }: { params: { slug: string } }) {
+  const post = await getPost(params.slug)
+  if (!post) notFound()
+
+  return <article>{post.content}</article>
+}
+```
+
+### Pattern 4: Monorepo CI/CD Pipeline
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+      - run: npm install
+      - run: npx turbo run build test lint
+        env:
+          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+          TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
+```
+
+## Utility Scripts
+
+Python utilities in `scripts/` directory:
+
+**nextjs-init.py** - Initialize Next.js project with best practices
+**turborepo-migrate.py** - Convert existing monorepo to Turborepo
+
+Usage examples:
+```bash
+# Initialize new Next.js app with TypeScript and recommended setup
+python scripts/nextjs-init.py --name my-app --typescript --app-router
+
+# Migrate existing monorepo to Turborepo with dry-run
+python scripts/turborepo-migrate.py --path ./my-monorepo --dry-run
+
+# Run tests
+cd scripts/tests
+pytest
+```
+
+## Best Practices
+
+**Next.js:**
+- Default to Server Components, use Client Components only when needed
+- Implement proper loading and error states
+- Use Image component for automatic optimization
+- Set proper metadata for SEO
+- Leverage caching strategies (force-cache, revalidate, no-store)
+
+**Turborepo:**
+- Structure monorepo with clear separation (apps/, packages/)
+- Define task dependencies correctly (^build for topological)
+- Configure outputs for proper caching
+- Enable remote caching for team collaboration
+- Use filters to run tasks on changed packages only
+
+**RemixIcon:**
+- Use line style for minimal interfaces, fill for emphasis
+- Maintain 24x24 grid alignment for crisp rendering
+- Provide aria-labels for accessibility
+- Use currentColor for flexible theming
+- Prefer webfonts for multiple icons, SVG for single icons
+
+## Resources
+
+- Next.js: https://nextjs.org/docs/llms.txt
+- Turborepo: https://turbo.build/repo/docs
+- RemixIcon: https://remixicon.com
+
+## Implementation Checklist
+
+Building with this stack:
+
+- [ ] Create project structure (single app or monorepo)
+- [ ] Configure TypeScript and ESLint
+- [ ] Set up Next.js with App Router
+- [ ] Configure Turborepo pipeline (if monorepo)
+- [ ] Install and configure RemixIcon
+- [ ] Implement routing and layouts
+- [ ] Add loading and error states
+- [ ] Configure image and font optimization
+- [ ] Set up data fetching patterns
+- [ ] Configure caching strategies
+- [ ] Add API routes as needed
+- [ ] Implement shared component library (if monorepo)
+- [ ] Configure remote caching (if monorepo)
+- [ ] Set up CI/CD pipeline
+- [ ] Configure deployment platform