ui8kit 1.0.5 → 1.1.0

package/README.md

@@ -1,194 +1,125 @@
-## Semantic Components Integration Guide
+# ui8kit CLI
 
-### CLI Installation (Recommended)
+Official CLI for bootstrapping and managing UI8Kit component workflows in Vite React projects.
 
-The semantic registry extends utility components with enhanced styling and behavior. Follow these steps:
+## Requirements
+
+- Node.js `>=18`
+- A Vite React project (for `init` and `add`)
+
+## Quick Start
 
-#### 1. Initialize Base Registry (Required)
 ```bash
-# Initialize utility registry first (foundation requirement)
-npx buildy-ui@latest init
+bunx ui8kit@latest init
 ```
 
-#### 2. Initialize Semantic Registry
-```bash
-# Initialize semantic registry
-npx buildy-ui@latest init --registry semantic
+Initialize with defaults (non-interactive):
 
-# Skip prompts and use defaults
-npx buildy-ui@latest init --yes --registry semantic
+```bash
+bunx ui8kit@latest init --yes
 ```
 
-#### 3. Add Semantic Components
-```bash
-# Add specific semantic components
-npx buildy-ui@latest add button card --registry semantic
-npx buildy-ui@latest add input --registry semantic
+## Commands
 
-# Install ALL semantic components at once
-npx buildy-ui@latest add --all --registry semantic
+### `init`
 
-# Preview what would be installed
-npx buildy-ui@latest add --all --dry-run --registry semantic
+Initialize UI8Kit structure and config in the current project.
 
-# Force overwrite existing files
-npx buildy-ui@latest add button --force --registry semantic
+```bash
+bunx ui8kit@latest init
+bunx ui8kit@latest init --yes
+bunx ui8kit@latest init --registry ui
 ```
 
-#### Project Structure After Installation
-```
-semantic/
-├── ui/              # Semantic UI components
-├── blocks/          # Semantic blocks
-├── components/      # Semantic components
-├── templates/       # Semantic templates
-└── buildy.config.json
-
-utility/             # Base registry (required)
-├── ui/
-├── blocks/
-└── buildy.config.json
-
-lib/                 # Shared utilities
-└── utils.ts
-```
+Options:
 
-## CSS Integration with Tailwind (PROD Mode)
+- `-y, --yes` Skip prompts and use defaults
+- `-r, --registry <type>` Registry type (default: `ui`)
 
-### Package Installation (Recommended for Tailwind projects)
+### `add`
 
-Since semantic CSS files contain Tailwind directives (`@apply`), they must be processed during build time:
+Install one or more components from the registry.
 
 ```bash
-# Install the CSS package
-npm install ui8kit@latest
-# or
-yarn add ui8kit@latest
-# or
-pnpm add ui8kit@latest
-# or
-bun add ui8kit@latest
+bunx ui8kit@latest add button
+bunx ui8kit@latest add button card
+bunx ui8kit@latest add --all
+bunx ui8kit@latest add badge --force
+bunx ui8kit@latest add button --dry-run
+bunx ui8kit@latest add --all --retry
 ```
 
-### Import in your CSS/SCSS files
-
-```css
-/* Import all semantic styles */
-@import "ui8kit/css/dist/semantic/index.css";
+Options:
 
-/* Or import individual components */
-@import "ui8kit/css/dist/semantic/button.css";
-@import "ui8kit/css/dist/semantic/card.css";
-@import "ui8kit/css/dist/semantic/input.css";
-```
-
-### Why Package Installation is Required
+- `-a, --all` Install all available components
+- `-f, --force` Overwrite existing files
+- `-r, --registry <type>` Registry type (default: `ui`)
+- `--dry-run` Show planned actions without writing files
+- `--retry` Enable retry logic for unstable connections
 
-Semantic CSS files contain Tailwind directives that need compilation:
+### `scan`
 
-```css
-/* Example from button.css */
-.button-default {
-  @apply bg-primary text-primary-foreground shadow-xs hover:bg-primary/90;
-}
+Scan source files and generate a registry manifest.
 
-.button-secondary {
-  @apply bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/90;
-}
+```bash
+bunx ui8kit@latest scan
+bunx ui8kit@latest scan --cwd ./apps/engine
+bunx ui8kit@latest scan --source ./src --output ./src/registry.json
 ```
 
-### CDN vs Package Comparison
+Options:
 
-| Method | Use Case | Tailwind Directives | Build Required |
-|--------|----------|-------------------|----------------|
-| **Package** | Production projects | ✅ Supported | ✅ Required |
-| **CDN** | Quick prototyping | ❌ Pre-compiled only | ❌ Not required |
+- `-r, --registry <type|path>` Registry type/path (default: `ui`)
+- `-o, --output <file>` Output registry file
+- `-s, --source <dir>` Source directory to scan
+- `--cwd <dir>` Working directory
 
-### Integration with Tailwind Config
+### `build`
 
-Add the package path to your `tailwind.config.js` for proper purging:
+Build a publishable registry from a registry JSON file.
 
-```js
-/** @type {import('tailwindcss').Config} */
-module.exports = {
-  content: [
-    "./src/**/*.{js,ts,jsx,tsx}",
-    "./node_modules/ui8kit/**/*.{js,ts,jsx,tsx}", // Add this line
-  ],
-  // ... rest of your config
-}
+```bash
+bunx ui8kit@latest build
+bunx ui8kit@latest build ./src/registry.json
+bunx ui8kit@latest build ./src/registry.json --output ./packages/registry/r
 ```
 
-**Note**: CDN links with `@import` URLs will remain as external references and won't be processed by Tailwind's build system.
+Options:
 
-### CDN Integration
+- `[registry]` Path to registry JSON (default: `./src/registry.json`)
+- `-o, --output <path>` Output directory (default: `./packages/registry/r`)
+- `-c, --cwd <cwd>` Working directory
 
-For projects that prefer CDN over CLI installation:
+## Typical Flow
 
-#### Compiled Semantic Stylesheet
-```html
-<!-- Load compiled semantic components -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ui8kit@latest/css/dist/styles.css">
-<!-- OR -->
-<link rel="stylesheet" href="https://unpkg.com/ui8kit@latest/css/dist/styles.css">
-```
+```bash
+# 1) Initialize project
+bunx ui8kit@latest init --yes
 
-### Usage Examples
-
-#### With CLI Installation
-```jsx
-// After CLI installation, components are available via aliases
-import { Button } from '@/semantic/ui/button'
-import { Card } from '@/semantic/ui/card'
-
-function App() {
-  return (
-    <Card>
-      <Button variant="secondary">Semantic Button</Button>
-    </Card>
-  )
-}
-```
+# 2) Add a component
+bunx ui8kit@latest add button
 
-#### With CDN Integration
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <!-- Load compiled semantic styles -->
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ui8kit@latest/css/dist/styles.css">
-</head>
-<body>
-  <!-- Use semantic classes directly -->
-  <div class="card">
-    <button class="button button-secondary button-lg">
-      Semantic Button
-    </button>
-  </div>
-</body>
-</html>
+# 3) Add everything from registry (optional)
+bunx ui8kit@latest add --all
 ```
 
-### Registry Dependencies
+## Local Development (this package)
 
-**Important**: Semantic registry requires utility registry as foundation:
-- ✅ Utility registry must be initialized first
-- ✅ Components must exist in utility before installing in semantic
-- ❌ Cannot use semantic registry without utility base
+From `packages/cli`:
 
-### Performance Considerations
+```bash
+npm install
+npm run dev
+```
 
-**CLI Method**:
-- ✅ Tree-shaking friendly
-- ✅ Only includes used components
-- ✅ TypeScript support
-- ✅ Local development workflow
+Build once:
 
-**CDN Method**:
-- ✅ No build step required
-- ✅ Instant integration
-- ✅ Cacheable across projects
-- ⚠️ Individual files = multiple HTTP requests
-- ⚠️ Full bundle may include unused styles
+```bash
+npm run build
+```
+
+Run compiled CLI locally:
 
-Choose CLI for development projects, CDN for quick prototyping or static sites.
+```bash
+node dist/index.js --help
+```

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node