npm package: @baskerhq/cli
Description: Official Basker CLI for theme development, deployment, and management
Author: Basker Team
Latest version: 0.1.3

# basker-theme-dev

A CLI tool for local development of static website themes with S3 sync.

<p align="center">
  <img src="https://via.placeholder.com/120x120/0047AB/FFFFFF?text=Basker" alt="Basker Logo" width="120" height="120">
</p>

[![npm version](https://img.shields.io/npm/v/basker-theme-dev.svg)](https://www.npmjs.com/package/basker-theme-dev)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

## Features

- **Real-time File Syncing** - Watch local directory for file changes and sync to S3
- **Local Development Server** - Serve files locally with Hono server
- **Hybrid Content Serving** - Prioritize local files over S3 content
- **Remote Proxy** - Access remote tenant site for files not available locally
- **Authentication Support** - Secure proxy integration with Payload CMS
- **Multi-tenant Themes** - Support for tenant and theme-specific development
- **Response Caching** - Local caching for improved performance
- **Quick Preview** - See local changes before they're synced to S3
- **Developer Experience** - Enhanced terminal output with status messages
- **Error Resilience** - Retry logic with exponential backoff for API failures
- **Performance Optimized** - Efficient handling of large directories

## Installation

```bash
# Install globally
npm install -g basker-theme-dev

# Using yarn
yarn global add basker-theme-dev

# Using pnpm
pnpm add -g basker-theme-dev

# Or use with npx
npx basker-theme-dev
```

## Quick Start

```bash
# Initialize configuration file
basker config init

# Start the development server
basker theme dev
```

## Usage

```bash
# Display help
basker --help

# Start the development server
basker theme dev --bucket my-s3-bucket 

# Specify port and directory
basker theme dev --bucket my-s3-bucket --port 8080 --directory ./theme

# Initialize a configuration file
basker config init
```

## Configuration

Create a `basker-theme.json` file in your project root:

```json
{
  "bucket": "my-s3-bucket",
  "port": 3000,
  "directory": "./theme",
  "awsRegion": "eu-west-1",
  "debounceDelay": 300,
  "tenantSlug": "example-tenant",
  "themeKey": "example-theme",
  "themeId": "677f79ceedfc09859d0e4cd1",
  "proxyUrl": "https://api.example.com/proxy",
  "ignorePatterns": [
    "node_modules/**",
    ".git/**"
  ],
  "contentType": {
    ".html": "text/html",
    ".css": "text/css"
  },
  "cacheControl": "public, max-age=3600"
}
```

### Configuration Options

| Option | Description | Default |
|--------|-------------|---------|
| `bucket` | S3 bucket name to sync with | *Required* |
| `port` | Local development server port | `3000` |
| `directory` | Local directory to watch | `./` |
| `awsRegion` | AWS region for S3 bucket | `eu-west-1` |
| `debounceDelay` | Milliseconds to wait before syncing after changes | `300` |
| `ignorePatterns` | Glob patterns for files to ignore | `[]` |
| `tenantSlug` | Tenant identifier for multi-tenant setup | `""` |
| `themeKey` | Theme identifier within tenant | `""` |
| `themeId` | Database ID of the theme (defaults to hardcoded value) | `"677f79ceedfc09859d0e4cd1"` |
| `proxyUrl` | URL for proxy service integration | `""` |
| `contentType` | Custom content type mappings | `{}` |
| `cacheControl` | Cache-Control header for S3 objects | `""` |

## AWS Credentials

Basker uses AWS SDK's default credential provider chain:

1. Environment variables: `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`
2. AWS profile in `~/.aws/credentials` 
3. EC2 instance profile or ECS task role (if running on AWS infrastructure)

## Command Reference

### `basker theme dev`

Start the development server and file watcher.

```bash
basker theme dev [options]
```

| Option | Description |
|--------|-------------|
| `--bucket`, `-b` | S3 bucket name |
| `--port`, `-p` | Server port |
| `--directory`, `-d` | Local directory to watch |
| `--region`, `-r` | AWS region |
| `--config`, `-c` | Path to config file |
| `--tenant`, `-t` | Tenant slug |
| `--theme`, `-k` | Theme key |
| `--proxy-url` | URL for proxy service |

### `basker config init`

Initialize a new configuration file.

```bash
basker config init [options]
```

| Option | Description |
|--------|-------------|
| `--force`, `-f` | Overwrite existing config file |

### `basker auth login`

Authenticate with the proxy service.

```bash
basker auth login [options]
```

| Option | Description |
|--------|-------------|
| `--email`, `-e` | Email for authentication |
| `--tenant`, `-t` | Tenant slug |

### `basker auth status`

Check authentication status.

```bash
basker auth status
```

### `basker auth logout`

Log out from the proxy service.

```bash
basker auth logout
```

## Examples

### Basic Usage

```bash
# Start server with default settings
basker theme dev --bucket my-bucket
```

### Custom Setup

```bash
# Start server with custom settings
basker theme dev --bucket my-bucket --port 8080 --directory ./src
```

### Using Configuration File

```bash
# Create a config file
basker config init

# Start using config file
basker theme dev
```

### Multi-tenant Theme Development

```bash
# Login to the proxy service
basker auth login --email user@example.com --tenant my-tenant

# Start development with tenant and theme options
basker theme dev --bucket my-bucket --tenant my-tenant --theme my-theme --proxy-url https://api.example.com/proxy
```

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

### Development

```bash
# Clone the repository
git clone https://github.com/your-username/basker-theme-dev.git
cd basker-theme-dev

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run in development mode with watch
pnpm dev

# Run tests
pnpm test
```

## Troubleshooting

### Common Issues

1. **AWS Authentication Errors**: Ensure AWS credentials are correctly configured
2. **Permission Denied**: Verify S3 bucket permissions
3. **Port Already in Use**: Change port using `--port` option
4. **Slow Syncing**: Adjust `debounceDelay` in config or exclude large files
5. **Proxy Authentication Failed**: Check your login credentials with `basker auth status` and try logging in again
6. **Tenant/Theme Not Found**: Verify your tenant slug and theme key are correct
7. **Proxy Connection Failed**: Check your network connection and the proxy URL
8. **Invalid Theme Path**: Ensure theme key format follows the required pattern

## License

MIT © [Basker Team](LICENSE)