npm package: @hyperobjekt/cli
Description: CLI tools and generators for Hyperobjekt projects
Author: Hyperobjekt
Latest version: 1.0.1

# @hyperobjekt/cli

CLI tools and generators for Hyperobjekt projects, including component swizzling and other development utilities.

## Installation

```bash
# In a Hyperobjekt project
pnpm add @hyperobjekt/cli

# Or install globally
pnpm add -g @hyperobjekt/cli
```

## Usage

### Component Swizzling

Swizzle components from `@hyperobjekt/ui` to customize them for your project:

#### Interactive Package and Component Selection

```bash
pnpm swizzle
# or
hyperobjekt swizzle
```

This will prompt you to:
1. Select which package to swizzle from (currently only `@hyperobjekt/ui`)
2. Choose a component from the available list
3. Specify where to place the swizzled component
4. Choose whether to copy associated CSS files

#### Direct Component Selection

```bash
pnpm swizzle ui
# or
hyperobjekt swizzle ui
```

This skips the package selection and goes directly to component selection.

#### Direct Component Swizzling

```bash
pnpm swizzle ui/Hero
pnpm swizzle ui/button
pnpm swizzle ui/CONTAINER
# or
hyperobjekt swizzle ui/Hero
```

This directly swizzles the specified component. Component names are case-insensitive.

### List Available Components

```bash
pnpm list-components
# or
hyperobjekt list-components
```

Shows all available components that can be swizzled from `@hyperobjekt/ui`.

## What is Swizzling?

Swizzling is the process of copying a component from a library into your project so you can modify it without affecting the original library component. This is useful when you need to:

- Customize the appearance or behavior of a component
- Add project-specific functionality
- Override default styles or props
- Create variations of existing components

## Project Setup

To use the CLI in your project, add it as a dependency and create npm scripts:

```json
{
  "dependencies": {
    "@hyperobjekt/cli": "workspace:*"
  },
  "scripts": {
    "swizzle": "hyperobjekt swizzle",
    "list-components": "hyperobjekt list-components"
  }
}
```

## Available Components

The following components are available for swizzling from `@hyperobjekt/ui`:

- AnchorLink
- Breadcrumbs
- Button
- ButtonLink
- Container
- Footer
- Header
- Heading
- Hero
- HorizontalRule
- Paragraph
- Text
- Typography

## File Structure

Swizzled components are placed in your `src/` directory. By default, they go into `src/components/ComponentName/`, but you can specify a custom path during the swizzling process.

Example structure after swizzling the Hero component:
```
src/
  components/
    Hero/
      index.jsx
      styles.module.css
      README.md
```

## Using Swizzled Components

After swizzling, update your imports to use the local component instead of the library version:

```jsx
// Before swizzling
import { Hero } from '@hyperobjekt/ui';

// After swizzling
import { Hero } from './components/Hero';
```

## Development

This package uses plop.js internally to handle code generation and file copying. The CLI automatically detects the location of `@hyperobjekt/ui` components whether you're in a monorepo or using it as an installed dependency.

## Future Enhancements

This CLI package is designed to be extensible. Future versions may include:

- Component generation templates
- Project scaffolding tools
- Code migration utilities
- Custom generator plugins

## Contributing

When adding new generators or features:

1. Add the generator to `src/plopfile.js`
2. Update the CLI documentation
3. Test with both monorepo and standalone project setups
4. Ensure proper error handling and user feedback