npm package: @firebits/theme-sync
Description: A powerful CLI tool for syncing theme files to a remote server with real-time watching and interactive confirmation.
Latest version: 1.1.3

# @firebits/theme-sync

A powerful CLI tool for syncing theme files to a remote server with real-time watching and interactive confirmation.

## Features

- 🔄 **Real-time file watching** - Automatically syncs files as they change
- 📊 **Full sync analysis** - Shows what files need to be uploaded, updated, or deleted
- 🗑️ **Interactive confirmation** - Asks for confirmation before deleting files
- 🚀 **Fast and efficient** - Uses file hashing to only sync what's changed
- 📁 **Directory support** - Handles nested directories and subdirectories
- 🔐 **Secure authentication** - API key-based authentication

## Installation

```bash
npm install -g @firebits/theme-sync
```

Or use with npx:

```bash
npx @firebits/theme-sync@latest sync -p ./my-theme -t my-theme -s http://localhost:8090 -k your-api-key
```

## Usage

### Start watching with initial sync

```bash
theme-sync sync -p ./my-theme -t my-theme -s http://localhost:8090 -k your-api-key
```

This will:
1. Perform an initial full sync to ensure server is up-to-date
2. Start watching for file changes
3. Automatically sync new, modified, or deleted files

### Start watching without initial sync

```bash
theme-sync sync -p ./my-theme -t my-theme -s http://localhost:8090 -k your-api-key --no-initial-sync
```

### Perform one-time full sync

```bash
theme-sync full-sync -p ./my-theme -t my-theme -s http://localhost:8090 -k your-api-key
```

This performs a full sync analysis and shows what will be changed before proceeding.

## Options

### sync command
- `-p, --path <path>` - Local theme directory path (required)
- `-t, --theme <name>` - Theme name (required)
- `-s, --server <url>` - Server sync URL (required)
- `-k, --key <key>` - Authentication key (required)
- `--no-initial-sync` - Skip initial full sync

### full-sync command
- `-p, --path <path>` - Local theme directory path (required)
- `-t, --theme <name>` - Theme name (required)
- `-s, --server <url>` - Server sync URL (required)
- `-k, --key <key>` - Authentication key (required)

## Examples

```bash
# Basic usage
theme-sync sync -p ./themes/my-theme -t my-theme -s http://localhost:8090 -k your-secret-key

# Skip initial sync
theme-sync sync -p ./themes/my-theme -t my-theme -s http://localhost:8090 -k your-secret-key --no-initial-sync

# One-time sync
theme-sync full-sync -p ./themes/my-theme -t my-theme -s http://localhost:8090 -k your-secret-key

# Using npx
npx @firebits/theme-sync@latest sync -p ./themes/my-theme -t my-theme -s http://localhost:8090 -k your-secret-key
```

## Server Requirements

The theme-sync CLI requires a compatible server with the following endpoints:

- `POST /themes/sync` - For individual file operations (update/delete)
- `POST /themes/full-sync-analysis` - For analyzing files without changes
- `POST /themes/full-sync` - For full synchronization with optional deletion

All endpoints require API key authentication via the `key` parameter.

## Theme Templates

### Head Template (`head.html`)

The `head.html` template in your theme's `templates/` directory allows you to customize the HTML tags that get injected into the `<head>` section of web pages. This replaces the previously hardcoded inject tags.

**Location**: `your-theme/templates/head.html`

**Example**:
```html
<!-- Custom inject tags for head section -->
<!-- Developers can customize these tags for their specific needs -->
<script src="/__theme/utils.js"></script>
<script src="/__theme/w3f/w3f.js"></script>
<script src="https://unpkg.com/alpinejs" defer></script>
<script src="/__theme/inject.js"></script>
<link rel="stylesheet" href="/__theme/inject.css">

<!-- Add your custom scripts and styles here -->
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css">
```

**Features**:
- ✅ **Customizable**: Add your own scripts, stylesheets, and meta tags
- ✅ **Flexible**: Include external CDN resources or local theme files
- ✅ **Isolated**: The `head.html` template is loaded separately from other templates
- ✅ **Optional**: If `head.html` doesn't exist, no head injection occurs

**Note**: The `head.html` template is automatically excluded from the general template loading to prevent duplication.

## Authentication

The CLI uses API key authentication. You need to:

1. **Configure keys on the server** in `config/keys.json`:
   ```json
   {
     "apiKeys": [
       "3604ddkkklsaEED",
       "your-secret-key-here",
       "another-key-for-different-client"
     ]
   }
   ```

2. **Use the key in CLI commands**:
   ```bash
   theme-sync sync -p ./my-theme -t my-theme -s http://localhost:8090 -k 3604ddkkklsaEED
   ```

## Interactive Confirmation

When performing a full sync, the tool will show you:

```
📋 Full Sync Analysis:
   📁 Total files: 15
   ⬆️ New files: 2
   🔄 Outdated files: 1
   🗑️ Files to delete: 3

🗑️ Files that will be deleted from server:
   - old-file.js
   - unused.css
   - temp.html

❓ Do you want to continue with deletion? (y/n):
```

Type `y` or `yes` to continue, or `n`/`no` to cancel.

## Requirements

- Node.js >= 16.0.0
- A compatible theme sync server
- Valid API key configured on the server

## License
MIT