@cloudwick/astral-ui-cli 0.1.0

package/README.md

@@ -0,0 +1,357 @@
+# Astral CLI
+
+A command-line tool for installing and managing Astral UI components in any codebase.
+
+## Installation
+
+```bash
+# Install globally with npm
+npm install -g @cloudwick/astral-ui-cli
+
+# Install globally with yarn
+yarn global add @cloudwick/astral-ui-cli
+
+# Or run directly with npx/yarn without installing
+npx @cloudwick/astral-ui-cli init
+# or more simply:
+npx astral-ui init
+```
+
+## Quick Start
+
+```bash
+# Initialize your project
+npx astral-ui init
+
+# Follow instructions to set up path aliases
+npx astral-ui setup-aliases
+
+# Add components
+npx astral-ui add button card
+
+# Start using in your code
+import { Button } from '@components/ui/button';
+import { cn } from '@utils';
+import { keyboardKeys, mobileBreakPoint } from '@constants';
+```
+
+## Workflow
+
+For the best experience, follow these steps in order:
+
+1. **Initialize** your project with `astral-ui init`
+2. **Set up path aliases** using `astral-ui setup-aliases` and follow the instructions
+3. **Add components** with `astral-ui add [component...]`
+4. **Repair Tailwind** if needed with `astral-ui repair-tailwind`
+5. **Import and use** components in your application
+
+## Commands
+
+### `init`
+
+Initialize a project with Astral Core configuration.
+
+```bash
+astral init
+```
+
+This command will:
+- Create a `components.json` configuration file
+- Set up necessary dependencies
+- Install Tailwind CSS if not already present
+- Add required configuration to existing Tailwind config or create a new one
+- Add utility functions
+
+#### Options
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--yes` | `-y` | Skip confirmation prompts |
+| `--defaults` | `-d` | Use default configuration |
+| `--force` | `-f` | Force overwrite of existing configuration |
+| `--cwd <dir>` | `-c` | Specify the working directory |
+| `--silent` | `-s` | Mute output |
+
+### `setup-aliases`
+
+Display instructions for setting up path aliases in your project.
+
+```bash
+astral setup-aliases
+```
+
+This command will:
+- Analyze your project structure
+- Detect the type of project (Next.js, Vite, Webpack, etc.)
+- Provide specific instructions for configuring path aliases based on your project type
+- Check for special configurations like tsconfig.app.json (used in Angular projects)
+
+#### Options
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--cwd <dir>` | `-c` | Specify the working directory |
+| `--silent` | `-s` | Mute output |
+
+#### Examples
+
+```bash
+# Generate instructions for current directory
+astral setup-aliases
+
+# Generate instructions for a specific project
+astral setup-aliases --cwd ./my-project
+```
+
+### `add`
+
+Add components to your project.
+
+```bash
+astral add [component...]
+```
+
+#### Options
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--yes` | `-y` | Skip confirmation prompts |
+| `--overwrite` | `-o` | Overwrite existing files |
+| `--cwd <dir>` | `-c` | Specify the working directory |
+| `--all` | `-a` | Add all available components |
+| `--path <path>` | `-p` | Specify the path to add the component to |
+| `--silent` | `-s` | Mute output |
+
+#### Examples
+
+```bash
+# Add specific components
+astral add button card select
+
+# Add all components
+astral add --all
+
+# Add a component to a specific directory
+astral add button --path ./components/custom
+```
+
+### `repair-tailwind`
+
+Repair Tailwind configuration when setup fails - only use if experiencing issues with Tailwind.
+
+```bash
+astral repair-tailwind
+```
+
+This command will:
+- Check for existing Tailwind configuration and create a timestamped backup
+- Create a new Tailwind configuration with the appropriate file extension for your project
+- Update CSS variables required by components
+- Ensure proper dependencies are installed
+
+#### Options
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--force` | `-f` | Force overwrite of existing configuration without prompting |
+| `--cwd <dir>` | `-c` | Specify the working directory |
+| `--silent` | `-s` | Mute output |
+
+## Configuration
+
+### components.json
+
+The `components.json` file is created during initialization and contains configuration for your project:
+
+```json
+{
+  "$schema": "./schema/components-config.schema.json",
+  "tailwind": {
+    "config": "tailwind.config.js",
+    "css": "src/styles/globals.css",
+  },
+  "aliases": {
+    "components": "src/components",
+    "utils": "src/utils",
+    "constants": "src/constants"
+  }
+}
+```
+
+You can edit this file to customize:
+- **tailwind.config**: Path to your Tailwind configuration file
+- **css**: Path to your global CSS file
+- **aliases**: Paths where components, utilities, and constants are installed
+
+> **Note**: The `utils` path in `components.json` is stored without a file extension. The CLI automatically adds `.ts` or `.js` extension based on whether your project uses TypeScript or JavaScript. When configuring path aliases, you should use the path without an extension as shown in the `components.json` file.
+
+### Components JSON Schema
+
+Alongside your `components.json`, the CLI generates a JSON Schema file at `schema/components-config.schema.json`.
+You can use this schema in your editor or CI to validate your configuration. It defines:
+- `$schema` (string): URI of this schema file.
+- `tailwind` (object): Paths to your Tailwind config (`config`) and CSS file (`css`).
+- `aliases` (object): Directories for `components`, `utils`, and `constants`.
+- `extensions` (string[]): File extensions to search for components.
+
+For full details, see `schema/components-config.schema.json` in your project.
+
+## Available Components
+
+| Component | Description |
+|-----------|-------------|
+| `button` | A button component with various styles, sizes, and states |
+| `card` | A card component for displaying content in a contained way |
+| `select` | A select component for selecting options from a list |
+
+## Using Components
+
+After adding components, you can import and use them in your application:
+
+### React/Next.js Example
+
+```tsx
+import { Button } from '@components/ui/button';
+import { Card, CardHeader, CardContent } from '@components/ui/card';
+import { cn } from '@utils';
+import { keyboardKeys, mobileBreakPoint } from '@constants';
+
+export function MyComponent() {
+  return (
+    <Card>
+      <CardHeader>My Card</CardHeader>
+      <CardContent>
+        <p>Card content goes here</p>
+        <Button 
+          className={cn("mt-4", "custom-class")}
+          variant="outline"
+        >
+          Click Me
+        </Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+### About the Utils File
+
+The CLI creates a utility file with the `cn` function that helps combine Tailwind classes. This file:
+
+- Is automatically created during initialization in the path specified in `components.json` (`utils` field)
+- Has the appropriate file extension (`.ts` for TypeScript projects, `.js` for JavaScript projects) added automatically
+- Should be imported in your components as `import { cn } from '@utils'` after setting up path aliases
+
+The `cn` function allows you to conditionally combine class names and automatically handles Tailwind class conflicts.
+
+## Styling Components
+
+The components in the registry require Tailwind CSS to be properly configured in your application. When you run `astral-ui init`, the CLI will:
+
+1. Check for an existing Tailwind configuration and upgrade it with required settings
+2. Create a CSS file with required CSS variables for component styling
+3. Generate a STYLING.md file with documentation on the styling system
+
+### Tailwind Integration
+
+The CLI intelligently handles existing Tailwind configurations:
+
+- Automatically detects existing configuration files with any extension (.js, .ts, .mjs, .cjs)
+- Creates a timestamped backup of any existing Tailwind configuration file
+- Creates a new tailwind.config file with the appropriate extension based on your project type:
+  - TypeScript projects: `.ts` extension
+  - ESM projects: `.mjs` extension
+  - CommonJS projects: `.js` extension
+  - CommonJS in an ESM package (with "type": "module"): `.cjs` extension
+- Preserves your project's language (TypeScript or JavaScript) and module system (ESM or CommonJS)
+
+Required Tailwind features included in the configuration:
+- Color system with RGB variables for primary, secondary, success, warning, error, and gray scales
+- Custom box shadows for card components
+- Dark mode support ("class" mode for theme toggling)
+- Animation utilities via tailwindcss-animate plugin
+
+### CSS Variables
+
+The CSS file includes all necessary CSS variables that components reference, including:
+
+- Base colors (primary, secondary, etc.)
+- State colors (success, error, warning)
+- Theme variables for light/dark mode
+
+## Troubleshooting
+
+### Path Alias Issues
+
+If you're having problems with imports:
+
+1. **Check your configuration**: Make sure the paths in tsconfig.json/jsconfig.json match your project structure
+2. **Framework-specific issues**:
+   - **Next.js**: Make sure you're using the correct import format for your Next.js version
+   - **Angular**: Configure paths in tsconfig.app.json instead of tsconfig.json
+   - **Create React App**: You'll need CRACO or similar to enable path aliases
+3. **Verify setup**: Run `astral-ui setup-aliases` again to get fresh instructions
+4. **Check components.json**: Make sure the paths in the "aliases" section match your project structure
+
+### Styling Issues
+
+If components don't appear correctly styled:
+
+1. Make sure the Tailwind CSS configuration is properly loaded in your application
+2. Verify the CSS variables are included in your main CSS file 
+3. Check that your component is properly importing the required utilities
+4. Run `astral-ui repair-tailwind` to create a fresh Tailwind configuration
+5. If you need to combine the new configuration with your existing customizations, use your backup file as a reference
+
+## Development
+
+### Setup
+
+```bash
+# Install dependencies
+yarn install
+```
+
+### Building
+
+```bash
+# Build the CLI
+yarn build
+
+# Watch for changes and rebuild automatically
+yarn dev
+```
+
+### Linting
+
+```bash
+# Run both ESLint and Stylelint
+yarn lint
+
+# Run only ESLint for TypeScript
+yarn lint:js
+
+# Run only Stylelint for CSS/SCSS
+yarn lint:style
+
+# Fix auto-fixable ESLint issues
+yarn lint:fix
+```
+
+### Testing
+
+```bash
+# Run tests
+yarn test
+```
+
+### Utilities
+
+```bash
+# Copy CSS variables from the UI library
+yarn copy-css
+```
+
+## License
+
+MIT