# @salesforce/ui-bundle-features

CLI tool for installing UI features into Salesforce UI Bundles.

## Installation

### Using npx (Recommended)

```bash
npx @salesforce/ui-bundle-features <command>
```

## Usage

### List Available Features

```bash
npx @salesforce/ui-bundle-features list
```

Search for specific features:

```bash
npx @salesforce/ui-bundle-features list --search "auth"
```

### Describe a Feature

Get detailed information about a specific feature:

```bash
npx @salesforce/ui-bundle-features describe authentication
```

This shows:

- Full description
- Dependencies (feature and npm packages)
- Files that will be copied
- Integration examples
- Components and capabilities

### Install a Feature

```bash
npx @salesforce/ui-bundle-features install <feature-name> --ui-bundle-dir <path>
```

Example:

```bash
npx @salesforce/ui-bundle-features install authentication --ui-bundle-dir my-ui-bundle
```

#### Installation Options

- `--ui-bundle-dir <name>` - **Required**. UI Bundle name, resolves to `<sfdx-source>/uiBundles/<name>`
- `--sfdx-source <path>` - Optional. SFDX source directory (default: `force-app/main/default`)
- `--dry-run` - Preview changes without making them
- `--verbose` or `-v` - Show detailed output
- `--yes` or `-y` - Skip conflicts (non-destructive)
- `--on-conflict <mode>` - Conflict resolution mode: `error`, `skip`, `overwrite`, or `prompt` (default)
- `--conflict-resolution <file>` - JSON file with per-file conflict resolutions

### Handling Conflicts

The recommended workflow for LLMs and automated tools:

1. **First, detect conflicts:**

   ```bash
   npx @salesforce/ui-bundle-features install authentication \
     --ui-bundle-dir my-ui-bundle \
     --on-conflict error
   ```

2. **If conflicts are detected**, create a resolution file:

   ```json
   {
     "path/to/file1": "overwrite",
     "path/to/file2": "skip",
     "path/to/file3": "overwrite"
   }
   ```

3. **Rerun with resolution file:**
   ```bash
   npx @salesforce/ui-bundle-features install authentication \
     --ui-bundle-dir my-ui-bundle \
     --conflict-resolution resolution.json
   ```

### Integration Examples

After installation, the CLI will list any `__example__` files that need manual integration:

```
Example files to integrate:
  src/__example__auth-app.tsx → Integrate into: src/app.tsx
```

For each example file:

1. Read the example file to see the integration pattern
2. Apply the pattern to your target file
3. Delete the example file after integration

## Available Features

Run `npx @salesforce/ui-bundle-features list` to see all available features.

Common features:

- **authentication** - Complete auth system with login, registration, password reset
- **shadcn** - UI component library based on shadcn/ui
- **global-search** - Salesforce object search
- **nav-menu** - Navigation menu layout
- **charts** - Analytics charts with Recharts
- **agentforce** - AI-powered conversation interface

## Local Development

### Building

```bash
npm run build
```

### Running locally

```bash
npm run dev -- <command>
```

Example:

```bash
npm run dev -- list
npm run dev -- install authentication --ui-bundle-dir /path/to/ui-bundle
```

### Global install from local build

```bash
npm run build && npm link
```

Then use `ui-bundle-features <command>` directly without `npx`.

## License

SEE LICENSE IN LICENSE.txt