@zvoove/unity-ui 2.20.0 → 2.21.0

package/bin/generate-skills.mjs

@@ -0,0 +1,683 @@
+#!/usr/bin/env node
+
+/**
+ * Unity UI — Agent Skills Generator
+ *
+ * Generates individual SKILL.md files for each Unity UI component
+ * following the Agent Skills standard (https://agentskills.io).
+ *
+ * Run from a project that has @zvoove/unity-ui installed:
+ *
+ *   npx unity-ui-skills                       → outputs to .claude/skills/
+ *   npx unity-ui-skills --output .cursor      → outputs to .cursor/skills/
+ *   npx unity-ui-skills --output ./my-skills  → outputs to ./my-skills/
+ *
+ * Skills enable progressive disclosure — AI agents scan skill metadata
+ * initially but load full content only when relevant to the current task.
+ */
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ─── Resolve llms.txt from the installed package ────────────────────────────
+
+function findLlmsTxt() {
+  // 1. Co-located with this bin (inside the published package)
+  const fromBin = path.resolve(__dirname, '..', 'dist', 'llms.txt');
+  if (fs.existsSync(fromBin)) return fromBin;
+
+  // 2. Fallback: llms.txt at the package root (dev / pre-build)
+  const fromRoot = path.resolve(__dirname, '..', 'llms.txt');
+  if (fs.existsSync(fromRoot)) return fromRoot;
+
+  return null;
+}
+
+// ─── CLI args ───────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let outputBase = '.claude';
+
+  for (let i = 0; i < args.length; i++) {
+    if ((args[i] === '--output' || args[i] === '-o') && args[i + 1]) {
+      outputBase = args[i + 1];
+      i++;
+    }
+    if (args[i] === '--help' || args[i] === '-h') {
+      console.log(`
+Unity UI — Agent Skills Generator
+
+Usage:
+  npx unity-ui-skills [options]
+
+Options:
+  -o, --output <dir>  Base directory for skills output (default: .claude)
+                      Skills will be written to <dir>/skills/unity-ui-*/SKILL.md
+  -h, --help          Show this help message
+
+Examples:
+  npx unity-ui-skills                       # → .claude/skills/
+  npx unity-ui-skills --output .cursor      # → .cursor/skills/
+  npx unity-ui-skills --output ./ai-skills  # → ./ai-skills/skills/
+`);
+      process.exit(0);
+    }
+  }
+
+  return { outputBase };
+}
+
+// ─── Name normalization ─────────────────────────────────────────────────────
+// Maps llms.txt header names → clean skill identifiers.
+const NAME_MAP = {
+  'Avatar & AvatarGroup': 'Avatar',
+  'Radio (RadioGroup + RadioButton)': 'Radio',
+  'Segment (SegmentGroup + SegmentButton)': 'Segment',
+  'Common Icons': '__SKIP__',
+  'File Type Icons': '__SKIP__',
+};
+
+// ─── shadcn/ui equivalence map ──────────────────────────────────────────────
+const SHADCN_MAP = {
+  Accordion: {
+    name: 'Accordion',
+    url: 'https://ui.shadcn.com/docs/components/accordion',
+  },
+  ActionCard: null,
+  Avatar: {
+    name: 'Avatar',
+    url: 'https://ui.shadcn.com/docs/components/avatar',
+  },
+  Badge: { name: 'Badge', url: 'https://ui.shadcn.com/docs/components/badge' },
+  Breadcrumbs: {
+    name: 'Breadcrumb',
+    url: 'https://ui.shadcn.com/docs/components/breadcrumb',
+  },
+  Button: {
+    name: 'Button',
+    url: 'https://ui.shadcn.com/docs/components/button',
+  },
+  Card: { name: 'Card', url: 'https://ui.shadcn.com/docs/components/card' },
+  ChatBubble: null,
+  Checkbox: {
+    name: 'Checkbox',
+    url: 'https://ui.shadcn.com/docs/components/checkbox',
+  },
+  Chip: {
+    name: 'Badge',
+    url: 'https://ui.shadcn.com/docs/components/badge',
+    note: 'shadcn Badge covers simple labels; Unity UI Chip adds interactivity (filter, input, suggestion types).',
+  },
+  CodeBlock: null,
+  ConfirmationCard: {
+    name: 'AlertDialog',
+    url: 'https://ui.shadcn.com/docs/components/alert-dialog',
+    note: 'AlertDialog is the closest equivalent for confirmation flows, but ConfirmationCard is an inline card, not a modal.',
+  },
+  ContentBlock: null,
+  DatePicker: {
+    name: 'DatePicker',
+    url: 'https://ui.shadcn.com/docs/components/date-picker',
+  },
+  Dialog: {
+    name: 'Dialog',
+    url: 'https://ui.shadcn.com/docs/components/dialog',
+  },
+  Divider: {
+    name: 'Separator',
+    url: 'https://ui.shadcn.com/docs/components/separator',
+  },
+  Expandable: {
+    name: 'Collapsible',
+    url: 'https://ui.shadcn.com/docs/components/collapsible',
+  },
+  FormLabel: {
+    name: 'Label',
+    url: 'https://ui.shadcn.com/docs/components/label',
+  },
+  Grid: null,
+  Icon: null,
+  InfoBox: {
+    name: 'Alert',
+    url: 'https://ui.shadcn.com/docs/components/alert',
+  },
+  MessageActions: null,
+  Pagination: {
+    name: 'Pagination',
+    url: 'https://ui.shadcn.com/docs/components/pagination',
+  },
+  PopUpMenu: {
+    name: 'DropdownMenu',
+    url: 'https://ui.shadcn.com/docs/components/dropdown-menu',
+    note: 'Also comparable to ContextMenu when using trigger="right-click".',
+  },
+  ProgressIndicator: {
+    name: 'Progress',
+    url: 'https://ui.shadcn.com/docs/components/progress',
+  },
+  Radio: {
+    name: 'RadioGroup',
+    url: 'https://ui.shadcn.com/docs/components/radio-group',
+  },
+  ScoreCard: null,
+  Segment: {
+    name: 'ToggleGroup',
+    url: 'https://ui.shadcn.com/docs/components/toggle-group',
+  },
+  Select: {
+    name: 'Select',
+    url: 'https://ui.shadcn.com/docs/components/select',
+    note: 'When searchable=true, comparable to Combobox.',
+  },
+  Sheet: { name: 'Sheet', url: 'https://ui.shadcn.com/docs/components/sheet' },
+  SideNavigation: {
+    name: 'Sidebar',
+    url: 'https://ui.shadcn.com/docs/components/sidebar',
+  },
+  Skeleton: {
+    name: 'Skeleton',
+    url: 'https://ui.shadcn.com/docs/components/skeleton',
+  },
+  Snackbar: {
+    name: 'Sonner (Toast)',
+    url: 'https://ui.shadcn.com/docs/components/sonner',
+  },
+  Stack: null,
+  Switch: {
+    name: 'Switch',
+    url: 'https://ui.shadcn.com/docs/components/switch',
+  },
+  Table: {
+    name: 'Table / DataTable',
+    url: 'https://ui.shadcn.com/docs/components/data-table',
+  },
+  Tabs: { name: 'Tabs', url: 'https://ui.shadcn.com/docs/components/tabs' },
+  Tag: {
+    name: 'Badge',
+    url: 'https://ui.shadcn.com/docs/components/badge',
+    note: 'shadcn Badge is the closest match. Unity UI Tag offers more color and tone variants.',
+  },
+  TextField: {
+    name: 'Input',
+    url: 'https://ui.shadcn.com/docs/components/input',
+  },
+  Textarea: {
+    name: 'Textarea',
+    url: 'https://ui.shadcn.com/docs/components/textarea',
+  },
+  Tooltip: {
+    name: 'Tooltip',
+    url: 'https://ui.shadcn.com/docs/components/tooltip',
+  },
+  TopBar: null,
+  Typography: null,
+  Uploader: null,
+  useBreakpoint: null,
+  useClickOutside: null,
+};
+
+// ─── Storybook documentation links ───────────────────────────────────────────
+// Maps component name → Storybook title path (as defined in *.stories.tsx).
+// URL: https://main--67c03f013fea08bb2f926e5f.chromatic.com/?path=/docs/<path>--docs
+const STORYBOOK_BASE =
+  'https://main--67c03f013fea08bb2f926e5f.chromatic.com/?path=/docs/';
+
+const STORYBOOK_MAP = {
+  Accordion: 'Components/Accordion',
+  ActionCard: 'Chat/ActionCard',
+  Avatar: 'Components/Avatar/Avatar',
+  Badge: 'Components/Badge',
+  Breadcrumbs: 'Navigation/Breadcrumbs',
+  Button: 'Components/Buttons/Button',
+  Card: 'Components/Card',
+  ChatBubble: 'Chat/ChatBubble',
+  Checkbox: 'Forms/Checkbox',
+  Chip: 'Components/Chip',
+  CodeBlock: 'Components/CodeBlock',
+  ConfirmationCard: 'Components/ConfirmationCard',
+  ContentBlock: 'Components/ContentBlock',
+  DatePicker: 'Forms/DatePicker',
+  Dialog: 'Components/Dialog',
+  Divider: 'Components/Divider',
+  Expandable: 'Components/Expandable',
+  FormLabel: 'Forms/FormLabel',
+  Grid: 'Layout/Grid',
+  Icon: 'Components/Icon',
+  InfoBox: 'Components/InfoBox',
+  MessageActions: 'Chat/MessageActions',
+  Pagination: 'Components/Pagination',
+  PopUpMenu: 'Components/PopUpMenu',
+  ProgressIndicator: 'Components/ProgressIndicator',
+  Radio: 'Forms/Radio/RadioGroup',
+  ScoreCard: 'Components/ScoreCard',
+  Segment: 'Components/Buttons/Segment/SegmentGroup',
+  Select: 'Forms/Select',
+  Sheet: 'Components/Sheet',
+  SideNavigation: 'Navigation/SideNavigation',
+  Skeleton: 'Components/Skeleton',
+  Snackbar: 'Components/Snackbar',
+  Stack: 'Layout/Stack',
+  Switch: 'Forms/Switch',
+  Table: 'Components/Table',
+  Tabs: 'Navigation/Tabs',
+  Tag: 'Components/Tag',
+  TextField: 'Forms/TextField',
+  Textarea: 'Forms/Textarea',
+  Tooltip: 'Components/Tooltip',
+  TopBar: 'Components/TopBar',
+  Typography: 'Components/Typography',
+  Uploader: 'Forms/Uploader',
+};
+
+function storybookUrl(name) {
+  const title = STORYBOOK_MAP[name];
+  if (!title) return null;
+  const slug = title.toLowerCase().replaceAll('/', '-');
+  return `${STORYBOOK_BASE}${slug}--docs`;
+}
+
+// ─── Component categories ───────────────────────────────────────────────────
+const CATEGORIES = {
+  Stack: 'layout',
+  Grid: 'layout',
+  Card: 'layout',
+  Divider: 'layout',
+  Expandable: 'layout',
+  ContentBlock: 'layout',
+  Typography: 'typography',
+  TextField: 'form',
+  Textarea: 'form',
+  Select: 'form',
+  Checkbox: 'form',
+  Radio: 'form',
+  Switch: 'form',
+  DatePicker: 'form',
+  Uploader: 'form',
+  FormLabel: 'form',
+  Button: 'action',
+  Segment: 'action',
+  PopUpMenu: 'action',
+  Table: 'data-display',
+  Tag: 'data-display',
+  Chip: 'data-display',
+  Avatar: 'data-display',
+  Badge: 'data-display',
+  Icon: 'data-display',
+  Skeleton: 'data-display',
+  ProgressIndicator: 'data-display',
+  CodeBlock: 'data-display',
+  Tabs: 'navigation',
+  Breadcrumbs: 'navigation',
+  SideNavigation: 'navigation',
+  Pagination: 'navigation',
+  TopBar: 'navigation',
+  Dialog: 'feedback',
+  Sheet: 'feedback',
+  Snackbar: 'feedback',
+  InfoBox: 'feedback',
+  ConfirmationCard: 'feedback',
+  Tooltip: 'feedback',
+  Accordion: 'compound',
+  ActionCard: 'compound',
+  ChatBubble: 'compound',
+  MessageActions: 'compound',
+  ScoreCard: 'compound',
+  useBreakpoint: 'hook',
+  useClickOutside: 'hook',
+};
+
+// Category-specific rules appended to each skill
+const CATEGORY_RULES = {
+  layout: [
+    '- Use Stack and Grid for layout instead of raw div + CSS',
+    '- Use the spacing scale for gap/padding/margin — never use arbitrary pixel values',
+  ],
+  form: [
+    '- Never create custom form inputs when this component exists',
+    '- Use responsive `density` prop when available for compact layouts',
+  ],
+  feedback: [
+    '- Never create custom overlays or toast systems when this component exists',
+  ],
+  typography: [
+    '- Use Typography for all text — never use raw `<p>`, `<h1>`, `<span>` etc.',
+  ],
+  hook: ['- Import hooks directly from `@zvoove/unity-ui`'],
+};
+
+// ─── Parse llms.txt ─────────────────────────────────────────────────────────
+
+function detectSection(line) {
+  const sectionHeaders = {
+    '## Setup': 'setup',
+    '## Responsive Props': 'responsive',
+    '## RULES FOR AI AGENTS': 'rules',
+    '## SPACING SCALE': 'spacing',
+    '## ICON NAMES': 'icons',
+  };
+
+  for (const [prefix, key] of Object.entries(sectionHeaders)) {
+    if (line.startsWith(prefix)) return key;
+  }
+  if (line.startsWith('## EXAMPLE:')) return 'example';
+  if (
+    /^## [A-Z]+ COMPONENTS?$/.test(line) ||
+    /^## (HOOKS|COMPOUND COMPONENTS|TYPOGRAPHY)$/.test(line)
+  ) {
+    return 'category-header';
+  }
+  return null;
+}
+
+function mergeComponent(components, buckets, name, lines) {
+  if (!name || lines.length === 0) return;
+  const normalizedName = NAME_MAP[name] ?? name;
+
+  if (normalizedName === '__SKIP__') {
+    buckets.icons.push('', `### ${name}`, ...lines);
+    return;
+  }
+  const text = lines.join('\n').trim();
+  components[normalizedName] = components[normalizedName]
+    ? components[normalizedName] + '\n\n' + text
+    : text;
+}
+
+function parseLlmsTxt(content) {
+  const components = {};
+  const buckets = {
+    setup: [],
+    responsive: [],
+    rules: [],
+    spacing: [],
+    icons: [],
+    example: [],
+  };
+
+  let activeSection = null;
+  let currentComponent = null;
+  let currentLines = [];
+
+  function flush() {
+    mergeComponent(components, buckets, currentComponent, currentLines);
+    currentComponent = null;
+    currentLines = [];
+  }
+
+  function handleSectionHeader(line) {
+    flush();
+    const section = detectSection(line);
+    activeSection = section === 'category-header' ? null : section;
+  }
+
+  function handleComponentHeader(line) {
+    flush();
+    currentComponent = line.slice(4).trim();
+    if (activeSection !== 'icons') activeSection = null;
+  }
+
+  function handleContentLine(line) {
+    if (currentComponent) {
+      currentLines.push(line);
+      return;
+    }
+    if (activeSection && buckets[activeSection]) {
+      buckets[activeSection].push(line);
+    }
+  }
+
+  for (const line of content.split('\n')) {
+    if (line === '---') continue;
+    if (line.startsWith('## ')) handleSectionHeader(line);
+    else if (line.startsWith('### ')) handleComponentHeader(line);
+    else handleContentLine(line);
+  }
+
+  flush();
+
+  const trimBucket = (key) => buckets[key].join('\n').trim();
+  return {
+    setup: trimBucket('setup'),
+    responsive: trimBucket('responsive'),
+    rules: trimBucket('rules'),
+    spacing: trimBucket('spacing'),
+    icons: trimBucket('icons'),
+    example: trimBucket('example'),
+    components,
+  };
+}
+
+// ─── Skill generators ───────────────────────────────────────────────────────
+
+function kebabCase(str) {
+  return str
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+function generateComponentSkill(name, content) {
+  const shadcn = SHADCN_MAP[name];
+  const category = CATEGORIES[name] || 'component';
+  const slug = kebabCase(name);
+  const docsUrl = storybookUrl(name);
+
+  let description = `${name} component from Unity UI (@zvoove/unity-ui). Category: ${category}.`;
+  if (shadcn) {
+    description += ` Comparable to shadcn/ui ${shadcn.name}.`;
+  }
+
+  const frontmatter = [
+    '---',
+    `name: unity-ui-${slug}`,
+    `description: "${description}"`,
+    `category: ${category}`,
+  ];
+  if (shadcn) frontmatter.push(`shadcn_equivalent: ${shadcn.name}`);
+  if (docsUrl) frontmatter.push(`docs: ${docsUrl}`);
+  frontmatter.push('---');
+
+  const body = [`# Unity UI — ${name}\n`];
+
+  const links = [];
+  if (docsUrl) links.push(`[Storybook docs](${docsUrl})`);
+  if (shadcn) links.push(`[shadcn/ui ${shadcn.name}](${shadcn.url})`);
+  if (links.length > 0) {
+    body.push(`> ${links.join(' | ')}`);
+    if (shadcn?.note) body.push(`> ${shadcn.note}`);
+    body.push('');
+  }
+
+  body.push(content);
+  body.push('\n## Rules\n');
+  body.push('- Always import from `@zvoove/unity-ui`');
+  body.push('- Never recreate components that exist in this library');
+
+  const extraRules = CATEGORY_RULES[category] || [];
+  body.push(...extraRules);
+  body.push(
+    '- Use responsive props where applicable (single value or breakpoint object)'
+  );
+
+  return frontmatter.join('\n') + '\n\n' + body.join('\n') + '\n';
+}
+
+function generateSetupSkill(parsed) {
+  const frontmatter = [
+    '---',
+    'name: unity-ui-setup',
+    'description: "Setup and installation for Unity UI (@zvoove/unity-ui). React component library with 40+ components, Tailwind CSS 4, dark mode, responsive props."',
+    'category: setup',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Unity UI — Setup & Overview
+
+> Unity UI (\`@zvoove/unity-ui\`) is a React component library with 40+ accessible, themeable components built with TypeScript and Tailwind CSS 4.
+
+${parsed.setup}
+
+## Responsive Props
+
+${parsed.responsive}
+
+## Spacing Scale
+
+${parsed.spacing}
+
+## Example: Contact Form
+
+${parsed.example}
+
+## Rules
+
+${parsed.rules}
+`
+  );
+}
+
+function generateIconsSkill(parsed) {
+  const frontmatter = [
+    '---',
+    'name: unity-ui-icons',
+    'description: "Icon names and usage for Unity UI (@zvoove/unity-ui). Semantic icon names based on Phosphor Icons. Use with <Icon name=\\"icon-name\\" /> component."',
+    'category: data-display',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Unity UI — Icons
+
+> Unity UI uses its own semantic icon names (not raw Phosphor icon names). Pass them via \`<Icon name="icon-name" />\`.
+
+${parsed.icons}
+
+## Rules
+
+- Always import Icon from \`@zvoove/unity-ui\`
+- Use semantic icon name strings — never import Phosphor icon components directly
+- Use \`getIconForFileExtension(extension)\` to resolve file extensions to icon names automatically
+`
+  );
+}
+
+function generateIndexSkill(componentNames) {
+  const shadcnRows = componentNames
+    .filter((n) => SHADCN_MAP[n])
+    .map(
+      (n) =>
+        `| ${n} | [${SHADCN_MAP[n].name}](${SHADCN_MAP[n].url}) | \`unity-ui-${kebabCase(n)}\` |`
+    );
+
+  const uniqueRows = componentNames
+    .filter((n) => !SHADCN_MAP[n])
+    .map((n) => `| ${n} | — | \`unity-ui-${kebabCase(n)}\` |`);
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui-index',
+    'description: "Component index for Unity UI (@zvoove/unity-ui). Maps all 40+ components to their shadcn/ui equivalents. Use this to find the right component."',
+    'category: index',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Unity UI — Component Index
+
+> Use this index to find the right Unity UI component. Each component has its own skill with full documentation.
+
+## Components with shadcn/ui Equivalents
+
+| Unity UI | shadcn/ui | Skill |
+|----------|-----------|-------|
+${shadcnRows.join('\n')}
+
+## Unity UI–Only Components
+
+| Unity UI | shadcn/ui | Skill |
+|----------|-----------|-------|
+${uniqueRows.join('\n')}
+
+## How to Use Skills
+
+Each skill is a standalone file with full props, usage examples, and rules for one component.
+AI agents should load the relevant skill when they need to use a specific component.
+`
+  );
+}
+
+// ─── Write skills to disk ───────────────────────────────────────────────────
+
+function writeSkill(outputDir, slug, content) {
+  const skillDir = path.join(outputDir, slug);
+  fs.mkdirSync(skillDir, { recursive: true });
+  fs.writeFileSync(path.join(skillDir, 'SKILL.md'), content, 'utf8');
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+function main() {
+  const { outputBase } = parseArgs(process.argv);
+
+  const llmsPath = findLlmsTxt();
+  if (!llmsPath) {
+    console.error(
+      'Could not find llms.txt. Make sure @zvoove/unity-ui is installed and built.'
+    );
+    process.exit(1);
+  }
+
+  const projectRoot = process.cwd();
+  const outputDir = path.resolve(projectRoot, outputBase, 'skills');
+  const content = fs.readFileSync(llmsPath, 'utf8');
+  const parsed = parseLlmsTxt(content);
+
+  // Clean previous unity-ui skills (leave other skills untouched)
+  if (fs.existsSync(outputDir)) {
+    for (const entry of fs.readdirSync(outputDir)) {
+      if (entry.startsWith('unity-ui-')) {
+        fs.rmSync(path.join(outputDir, entry), { recursive: true });
+      }
+    }
+  }
+
+  const componentNames = Object.keys(parsed.components).sort();
+  let count = 0;
+
+  // Component skills
+  for (const [name, componentContent] of Object.entries(parsed.components)) {
+    writeSkill(
+      outputDir,
+      `unity-ui-${kebabCase(name)}`,
+      generateComponentSkill(name, componentContent)
+    );
+    count++;
+  }
+
+  // Meta skills
+  writeSkill(outputDir, 'unity-ui-setup', generateSetupSkill(parsed));
+  writeSkill(outputDir, 'unity-ui-icons', generateIconsSkill(parsed));
+  writeSkill(outputDir, 'unity-ui-index', generateIndexSkill(componentNames));
+  count += 3;
+
+  const relOutput = path.relative(projectRoot, outputDir);
+  console.log(`\n  Unity UI — Agent Skills Generator\n`);
+  console.log(`  ✅ Generated ${count} skills in ${relOutput}/\n`);
+  console.log(`     ${componentNames.length} component skills`);
+  console.log(`     1 setup skill (installation, spacing, responsive props)`);
+  console.log(`     1 icons skill (all icon names)`);
+  console.log(`     1 index skill (shadcn/ui mapping table)\n`);
+  console.log(`  Your AI agent can now discover and use Unity UI components.`);
+  console.log(`  Skills are loaded on-demand — only relevant ones are read.\n`);
+}
+
+main();