m9sh 0.1.0 → 0.2.0

data/M9SH_CLI.md

@@ -0,0 +1,453 @@
+# M9sh CLI - Component Generator
+
+A powerful CLI tool for generating and managing M9sh components, inspired by shadcn/ui CLI.
+
+## Features
+
+- 🎨 **Component Generation** - Generate individual components or all at once
+- 📦 **Dependency Management** - Automatically resolves and installs dependencies
+- 🔧 **Customizable** - Override namespace, paths, and other settings
+- 🔄 **Sync Components** - Update existing components to latest versions
+- 📋 **Component Registry** - Browse all available components
+- ⚙️ **YAML Configuration** - Project-specific configuration via `m9sh.yml`
+
+## Installation
+
+The CLI is already included in this project. Simply run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+### 1. Initialize Configuration
+
+```bash
+bin/m9sh init
+```
+
+This will create an interactive setup to configure:
+- Component namespace (e.g., `M9sh`, `MyApp::UI`)
+- Components directory path
+- JavaScript controllers path
+- Tailwind and CSS file paths
+
+Non-interactive initialization:
+
+```bash
+bin/m9sh init --interactive=false \
+  --namespace=MyComponents \
+  --components_path=app/components/ui \
+  --javascript_path=app/javascript/controllers/ui
+```
+
+### 2. List Available Components
+
+```bash
+bin/m9sh list
+```
+
+Show only installed components:
+
+```bash
+bin/m9sh list -i
+```
+
+Show only available (not installed) components:
+
+```bash
+bin/m9sh list -a
+```
+
+### 3. Add a Component
+
+```bash
+bin/m9sh add button
+```
+
+This will:
+- Install the `button` component
+- Automatically install dependencies (`base`, `utilities`)
+- Copy files to configured directories
+- Transform namespaces if custom namespace is set
+
+Add multiple components:
+
+```bash
+bin/m9sh add button
+bin/m9sh add card
+bin/m9sh add dialog
+```
+
+Add all components:
+
+```bash
+bin/m9sh add --all
+```
+
+### 4. Get Component Information
+
+```bash
+bin/m9sh info button
+```
+
+Shows:
+- Component description
+- Installation status
+- Dependencies
+- Files that will be generated
+
+### 5. Sync Components
+
+Update a component to the latest version:
+
+```bash
+bin/m9sh sync button
+```
+
+Sync all components:
+
+```bash
+bin/m9sh sync --all
+```
+
+## Commands Reference
+
+### `init`
+
+Initialize M9sh configuration.
+
+**Options:**
+- `--interactive` / `-i` - Interactive setup (default: true)
+- `--namespace` - Component namespace
+- `--components_path` - Path to components directory
+- `--javascript_path` - Path to JavaScript controllers
+
+**Examples:**
+
+```bash
+# Interactive setup
+bin/m9sh init
+
+# Non-interactive with defaults
+bin/m9sh init --interactive=false
+
+# Custom configuration
+bin/m9sh init --interactive=false \
+  --namespace=MyApp::Components \
+  --components_path=app/components/myapp \
+  --javascript_path=app/javascript/controllers/myapp
+```
+
+### `add COMPONENT`
+
+Add a component with its dependencies.
+
+**Options:**
+- `--namespace` - Override namespace from config
+- `--components_path` - Override components path
+- `--javascript_path` - Override JavaScript path
+- `--force` / `-f` - Overwrite existing files
+- `--all` - Install all components
+
+**Examples:**
+
+```bash
+# Add single component
+bin/m9sh add button
+
+# Add with force (overwrite)
+bin/m9sh add button --force
+
+# Add with custom namespace
+bin/m9sh add button --namespace=CustomNamespace
+
+# Add all components
+bin/m9sh add --all
+```
+
+### `list`
+
+List all available components.
+
+**Options:**
+- `--installed` / `-i` - Show only installed components
+- `--available` / `-a` - Show only available components
+
+**Examples:**
+
+```bash
+# List all
+bin/m9sh list
+
+# Only installed
+bin/m9sh list -i
+
+# Only available
+bin/m9sh list -a
+```
+
+### `sync COMPONENT`
+
+Update a component to the latest version.
+
+**Options:**
+- `--all` - Sync all components
+- `--namespace` - Override namespace from config
+- `--components_path` - Override components path
+- `--javascript_path` - Override JavaScript path
+
+**Examples:**
+
+```bash
+# Sync single component
+bin/m9sh sync button
+
+# Sync all
+bin/m9sh sync --all
+```
+
+### `info COMPONENT`
+
+Show information about a component.
+
+**Examples:**
+
+```bash
+bin/m9sh info button
+bin/m9sh info accordion
+```
+
+### `version`
+
+Show M9sh CLI version.
+
+```bash
+bin/m9sh version
+```
+
+## Configuration File
+
+The `m9sh.yml` file stores your project configuration:
+
+```yaml
+---
+namespace: M9sh
+components_path: app/components/m9sh
+javascript_path: app/javascript/controllers/m9sh
+tailwind_config: tailwind.config.js
+css_file: app/assets/stylesheets/application.tailwind.css
+style: default
+```
+
+### Configuration Options
+
+- **namespace**: The Ruby module namespace for components (e.g., `M9sh`, `MyApp::UI`)
+- **components_path**: Directory where component Ruby files are generated
+- **javascript_path**: Directory where Stimulus controller files are generated
+- **tailwind_config**: Path to Tailwind configuration file
+- **css_file**: Path to main CSS file
+- **style**: Component style variant (currently only `default`)
+
+## Available Components
+
+### Base Components
+- **base** - Base component class
+- **utilities** - Helper module for class names
+
+### Form Components
+- **button** - Button with variants (default, outline, ghost, destructive, etc.)
+- **input** - Text input
+- **label** - Form label
+- **checkbox** - Checkbox input
+- **textarea** - Multi-line text input
+- **select** - Dropdown select
+- **switch** - Toggle switch (with Stimulus)
+- **slider** - Slider input (with Stimulus)
+- **radio_group** - Radio button group (with Stimulus)
+
+### Layout Components
+- **card** - Container with header, body, footer
+- **table** - Styled table
+- **separator** - Horizontal/vertical separator
+- **main** - Main content wrapper
+
+### Feedback Components
+- **alert** - Alert notifications
+- **toast** - Toast notifications (with Stimulus)
+- **toaster** - Toast container (with Stimulus)
+- **progress** - Progress bar
+- **spinner** - Loading spinner
+- **skeleton** - Loading skeleton
+
+### Navigation Components
+- **breadcrumb** - Breadcrumb navigation
+- **navigation_menu** - Navigation menu (with Stimulus)
+- **sidebar** - Sidebar navigation (with Stimulus)
+- **tabs** - Tab navigation (with Stimulus)
+
+### Display Components
+- **avatar** - User avatar
+- **badge** - Status badge
+- **typography** - Typography styles
+
+### Interactive Components
+- **accordion** - Collapsible accordion (with Stimulus)
+- **dialog** - Modal dialog (with Stimulus)
+- **alert_dialog** - Confirmation dialog (with Stimulus)
+- **sheet** - Side sheet (with Stimulus)
+- **tooltip** - Tooltip (with Stimulus)
+- **popover** - Popover (with Stimulus)
+- **hover_card** - Hover card (with Stimulus)
+- **collapsible** - Collapsible section (with Stimulus)
+- **dropdown_menu** - Dropdown menu (with Stimulus)
+- **toggle** - Toggle button (with Stimulus)
+
+### Theme Components
+- **theme_toggle** - Dark/light theme toggle
+
+## How It Works
+
+### Component Registry
+
+The CLI uses `lib/m9sh/registry.yml` to define all available components, their dependencies, and file locations.
+
+### Dependency Resolution
+
+When you add a component, the CLI automatically:
+1. Resolves all dependencies recursively
+2. Installs dependencies in correct order
+3. Copies component files
+4. Transforms namespaces if needed
+
+For example, adding `button` will also install:
+- `base` (base component class)
+- `utilities` (helper module)
+
+### Namespace Transformation
+
+If you use a custom namespace (e.g., `MyApp::Components`), the CLI automatically:
+- Transforms module declarations: `module M9sh` → `module MyApp::Components`
+- Updates class names: `M9sh::ButtonComponent` → `MyApp::Components::ButtonComponent`
+- Updates Stimulus controller identifiers: `m9sh--button` → `myapp-components--button`
+- Updates data attributes accordingly
+
+## Examples
+
+### Example 1: Start a New Project
+
+```bash
+# Initialize with defaults
+bin/m9sh init
+
+# Add core components
+bin/m9sh add button
+bin/m9sh add card
+bin/m9sh add input
+
+# Check what's installed
+bin/m9sh list -i
+```
+
+### Example 2: Custom Namespace
+
+```bash
+# Initialize with custom namespace
+bin/m9sh init --interactive=false \
+  --namespace=MyApp::UI \
+  --components_path=app/components/myapp/ui \
+  --javascript_path=app/javascript/controllers/myapp/ui
+
+# Add components
+bin/m9sh add button
+bin/m9sh add dialog
+```
+
+Result in `app/components/myapp/ui/button_component.rb`:
+```ruby
+module MyApp
+  module UI
+    class ButtonComponent < BaseComponent
+      # ...
+    end
+  end
+end
+```
+
+### Example 3: Sync All Components
+
+```bash
+# Update all components to latest version
+bin/m9sh sync --all
+```
+
+## Troubleshooting
+
+### "Configuration not found"
+
+Run `bin/m9sh init` first to create the configuration file.
+
+### "Component not found in registry"
+
+Check available components with `bin/m9sh list` or verify the component name.
+
+### "Source file not found"
+
+This happens when:
+- You're not in the project root directory
+- The source components don't exist in `app/components/m9sh/`
+
+### Overwrite Existing Files
+
+Use the `--force` flag:
+
+```bash
+bin/m9sh add button --force
+# or
+bin/m9sh sync button
+```
+
+## Development
+
+### Adding New Components to Registry
+
+Edit `lib/m9sh/registry.yml`:
+
+```yaml
+components:
+  my_component:
+    name: "My Component"
+    description: "Description here"
+    files:
+      - app/components/m9sh/my_component.rb
+      - app/javascript/controllers/m9sh/my_component_controller.js
+    dependencies:
+      - base
+      - utilities
+```
+
+### Registry File Structure
+
+```yaml
+components:
+  component_key:
+    name: "Display Name"
+    description: "Component description"
+    files:  # List of files to copy
+      - path/to/component.rb
+      - path/to/controller.js
+    dependencies:  # Components that must be installed first
+      - base
+      - another_component
+```
+
+## License
+
+MIT License - See LICENSE file for details.
+
+## Credits
+
+- Inspired by [shadcn/ui](https://ui.shadcn.com)
+- Built with [Thor](https://github.com/rails/thor)
+- Part of the M9sh component library