ui8kit 1.0.6 → 1.3.0

package/README.md

@@ -1,194 +1,211 @@
-## Semantic Components Integration Guide
-
-### CLI Installation (Recommended)
-
-The semantic registry extends utility components with enhanced styling and behavior. Follow these steps:
-
-#### 1. Initialize Base Registry (Required)
-```bash
-# Initialize utility registry first (foundation requirement)
-npx buildy-ui@latest init
-```
-
-#### 2. Initialize Semantic Registry
-```bash
-# Initialize semantic registry
-npx buildy-ui@latest init --registry semantic
-
-# Skip prompts and use defaults
-npx buildy-ui@latest init --yes --registry semantic
-```
-
-#### 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
-
-# Install ALL semantic components at once
-npx buildy-ui@latest add --all --registry semantic
-
-# Preview what would be installed
-npx buildy-ui@latest add --all --dry-run --registry semantic
-
-# Force overwrite existing files
-npx buildy-ui@latest add button --force --registry semantic
-```
-
-#### 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
-```
-
-## CSS Integration with Tailwind (PROD Mode)
-
-### Package Installation (Recommended for Tailwind projects)
-
-Since semantic CSS files contain Tailwind directives (`@apply`), they must be processed during build time:
-
-```bash
-# Install the CSS package
-npm install ui8kit@latest
-# or
-yarn add ui8kit@latest
-# or
-pnpm add ui8kit@latest
-# or
-bun add ui8kit@latest
-```
-
-### Import in your CSS/SCSS files
-
-```css
-/* Import all semantic styles */
-@import "ui8kit/css/dist/semantic/index.css";
-
-/* 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
-
-Semantic CSS files contain Tailwind directives that need compilation:
-
-```css
-/* Example from button.css */
-.button-default {
-  @apply bg-primary text-primary-foreground shadow-xs hover:bg-primary/90;
-}
-
-.button-secondary {
-  @apply bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/90;
-}
-```
-
-### CDN vs Package Comparison
-
-| Method | Use Case | Tailwind Directives | Build Required |
-|--------|----------|-------------------|----------------|
-| **Package** | Production projects | ✅ Supported | ✅ Required |
-| **CDN** | Quick prototyping | ❌ Pre-compiled only | ❌ Not required |
-
-### Integration with Tailwind Config
-
-Add the package path to your `tailwind.config.js` for proper purging:
-
-```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
-}
-```
-
-**Note**: CDN links with `@import` URLs will remain as external references and won't be processed by Tailwind's build system.
-
-### CDN Integration
-
-For projects that prefer CDN over CLI installation:
-
-#### 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">
-```
-
-### 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>
-  )
-}
-```
-
-#### 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>
-```
-
-### Registry Dependencies
-
-**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
-
-### Performance Considerations
-
-**CLI Method**:
-- ✅ Tree-shaking friendly
-- ✅ Only includes used components
-- ✅ TypeScript support
-- ✅ Local development workflow
-
-**CDN Method**:
-- ✅ No build step required
-- ✅ Instant integration
-- ✅ Cacheable across projects
-- ⚠️ Individual files = multiple HTTP requests
-- ⚠️ Full bundle may include unused styles
-
-Choose CLI for development projects, CDN for quick prototyping or static sites.
+# ui8kit CLI
+
+Official CLI for bootstrapping and managing UI8Kit component workflows in Vite React projects.
+
+## Requirements
+
+- Node.js `>=18`
+- A Vite React project (for `init` and `add`)
+
+## Quick Start
+
+```bash
+bunx ui8kit@latest init
+```
+
+Initialize with defaults (non-interactive):
+
+```bash
+bunx ui8kit@latest init --yes
+```
+
+## Commands
+
+### `init`
+
+Initialize UI8Kit structure and config in the current project.
+
+```bash
+bunx ui8kit@latest init
+bunx ui8kit@latest init --yes
+bunx ui8kit@latest init --registry ui
+```
+
+Options:
+
+- `-y, --yes` Skip prompts and use defaults
+- `-r, --registry <type>` Registry type (default: `ui`)
+
+When running without `--yes`, `init` now asks for:
+
+- Global CSS file path (default: `src/index.css`)
+- Import alias for components (default: `@/components`)
+
+`typescript` is always set to `true` and `framework` is fixed to `vite-react`.
+
+### `add`
+
+Install one or more components from the registry.
+
+```bash
+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
+bunx ui8kit@latest --no-cache add button --dry-run
+```
+
+Calling `add` without component arguments opens an interactive multiselect list grouped by component type.
+Resolved registry dependencies are installed in dependency order automatically.
+`add` now prints progress counters for multi-component installs in the format `[n/total]`.
+`--dry-run` now also shows:
+- full target file paths
+- overwrite/create status for each file
+- registry dependency tree
+- compact diff preview for files that already exist locally
+
+Options:
+
+- `-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
+- `--no-cache` (root option) bypasses cache for this run.
+
+### `list`
+
+List available components from the registry.
+Grouped by component type and sorted alphabetically.
+
+```bash
+bunx ui8kit@latest list
+bunx ui8kit@latest list --registry ui
+bunx ui8kit@latest list --json
+```
+
+Options:
+
+- `-r, --registry <type>` Registry type (default: `ui`)
+- `--json` Print JSON output instead of table
+
+### `diff`
+
+Show differences between local components and registry versions using unified diff output.
+Useful to check which installed components are outdated.
+
+```bash
+bunx ui8kit@latest diff
+bunx ui8kit@latest diff button
+bunx ui8kit@latest diff --json
+```
+
+Options:
+
+- `[component]` Optional component name
+- `-r, --registry <type>` Registry type (default: `ui`)
+- `--json` Print diff summary as JSON
+
+Examples:
+
+```bash
+bunx ui8kit@latest diff button
+```
+
+### `cache`
+
+Manage local registry cache.
+
+```bash
+bunx ui8kit@latest cache clear
+```
+
+### `info`
+
+Show local environment and configuration diagnostics.
+
+```bash
+bunx ui8kit@latest info
+bunx ui8kit@latest --no-cache info
+```
+
+Use `--no-cache` in any command to skip reading cached registry data.
+
+```bash
+bunx ui8kit@latest --no-cache diff
+bunx ui8kit@latest --no-cache list --json
+```
+
+### `scan`
+
+Scan source files and generate a registry manifest.
+
+```bash
+bunx ui8kit@latest scan
+bunx ui8kit@latest scan --source ./src --output ./src/registry.json
+```
+
+Options:
+
+- `-r, --registry <type|path>` Registry type/path (default: `ui`)
+- `-o, --output <file>` Output registry file
+- `-s, --source <dir>` Source directory to scan
+
+### `build`
+
+Build a publishable registry from a registry JSON file.
+
+```bash
+bunx ui8kit@latest build
+bunx ui8kit@latest build ./src/registry.json
+bunx ui8kit@latest build ./src/registry.json --output ./packages/registry/r
+```
+
+Options:
+
+- `[registry]` Path to registry JSON (default: `./src/registry.json`)
+- `-o, --output <path>` Output directory (default: `./packages/registry/r`)
+
+### Global options
+
+These options work for all commands and are defined at the CLI root:
+
+- `-c, --cwd <dir>` Working directory for command execution (default: current directory)
+- `-v, --verbose` Enable verbose output including debug logs from registry/CDN operations
+- `--no-cache` Bypass local filesystem cache for registry lookups
+
+## Typical Flow
+
+```bash
+# 1) Initialize project
+bunx ui8kit@latest init --yes
+
+# 2) Add a component
+bunx ui8kit@latest add button
+
+# 3) Add everything from registry (optional)
+bunx ui8kit@latest add --all
+```
+
+## Local Development (this package)
+
+From `packages/cli`:
+
+```bash
+npm install
+npm run dev
+```
+
+Build once:
+
+```bash
+npm run build
+```
+
+Run compiled CLI locally:
+
+```bash
+node dist/index.js --help
+```

package/dist/index.d.ts

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