npm package: @skill-kit/sync
Description: Cross-device Skill synchronization with cloud backends for Skill Kit
Latest version: 1.0.0

# @skill-kit/sync

Cross-device Skill synchronization with cloud backends for Skill Kit.

## Features

- Push local skills to cloud storage
- Pull skills from cloud to local
- Conflict detection and resolution (local-wins, remote-wins, latest-wins, manual)
- Offline queue for operations when network is unavailable
- Multiple backend support (Supabase, GitHub Gist)
- Selective sync with glob patterns
- Incremental sync based on content hash

## Installation

```bash
npm install @skill-kit/sync
# or
pnpm add @skill-kit/sync
```

## CLI Usage

### Push Skills

```bash
# Push all skills to cloud
skill-sync push

# Push with options
skill-sync push --dir ~/.skill-kit/skills --force --dry-run

# Push specific skills
skill-sync push --include "workflow-*.md"

# Use GitHub Gist backend
skill-sync push --backend github-gist
```

### Pull Skills

```bash
# Pull all skills from cloud
skill-sync pull

# Pull with conflict resolution
skill-sync pull --conflict latest-wins

# Force overwrite local
skill-sync pull --force

# Delete local skills not in remote
skill-sync pull --delete
```

### Check Status

```bash
# Show sync status
skill-sync status

# JSON output
skill-sync status --json
```

### Manage Offline Queue

```bash
# List queued operations
skill-sync queue --list

# Process queue
skill-sync queue --flush

# Clear queue
skill-sync queue --clear
```

## Programmatic Usage

```typescript
import { SyncEngine, createBackend, push, pull, syncStatus } from '@skill-kit/sync';

// Create and authenticate backend
const backend = createBackend('supabase');
await backend.authenticate({
  type: 'supabase',
  url: process.env.SUPABASE_URL,
  key: process.env.SUPABASE_KEY,
});

// Push skills
const pushResult = await push(backend, {
  skillsDir: '~/.skill-kit/skills',
  force: false,
  dryRun: false,
});

// Pull skills
const pullResult = await pull(backend, {
  skillsDir: '~/.skill-kit/skills',
  force: false,
});

// Check status
const status = await syncStatus(backend, {
  skillsDir: '~/.skill-kit/skills',
});

console.log(`Synced: ${status.synced}`);
console.log(`Modified locally: ${status.modifiedLocal}`);
console.log(`Conflicts: ${status.conflicts}`);
```

## Environment Variables

### Supabase Backend

```bash
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-anon-key
# Optional user auth
SUPABASE_EMAIL=user@example.com
SUPABASE_PASSWORD=password
```

### GitHub Gist Backend

```bash
GITHUB_TOKEN=ghp_your_token
# Optional: specify existing gist
GITHUB_GIST_ID=abc123
```

## Configuration

Add to your `.skillkitrc.json`:

```json
{
  "sync": {
    "provider": "supabase",
    "autoSync": false
  }
}
```

## Conflict Resolution Strategies

| Strategy      | Behavior                                  |
| ------------- | ----------------------------------------- |
| `local-wins`  | Always keep local version                 |
| `remote-wins` | Always keep remote version                |
| `latest-wins` | Keep the most recently modified version   |
| `manual`      | Skip conflicts, require manual resolution |

## API Reference

### SyncEngine

```typescript
const engine = new SyncEngine(backend, config);
await engine.push(options);
await engine.pull(options);
await engine.status();
```

### Backends

```typescript
// Supabase
const supabase = new SupabaseBackend();
await supabase.authenticate({ type: 'supabase', url, key });

// GitHub Gist
const gist = new GitHubGistBackend();
await gist.authenticate({ type: 'github', token });
```

### OfflineQueue

```typescript
const queue = new OfflineQueue();
await queue.load();

await queue.enqueue('push', skill);
await queue.flush();
```

## License

MIT