npm package: @fsco/autosync
Description: FSCO AutoSync CLI Tool
Author: FSCO
Latest version: 0.3.1

<p align="center">
  <img src="https://dev.fsco.io/assets/logo-documentation.svg" alt="@fsco/autosync" width="140"/>
</p>

<h1 align="center">@fsco/autosync</h1>

<p align="center">
  🔁 CLI tool for syncing files & generating TypeScript models from OpenAPI specs.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@fsco/autosync"><img src="https://img.shields.io/npm/v/@fsco/autosync.svg" alt="npm version"></a>
  <a href="https://github.com/fsco/autosync"><img src="https://img.shields.io/github/stars/fsco/autosync?style=social" alt="GitHub stars"></a>
</p>

---

## 🚀 Features

- 📦 **File Synchronization** — Sync files between folders with intelligent change detection
- 📋 **OpenAPI Schema to TypeScript** — Generate DTOs/clients from `.yaml` or `.json`
- 🔄 **Real-time File Watching** — Automatic sync on file changes
- 🚀 **Fast Generation** — Native Bun generator + OpenAPI generator fallback
- 📦 **Schema Bundling** — Automatic Redocly bundling to resolve `$ref` issues
- 🐳 **Docker Support** — Containerized development environment
- 📊 **Progress Tracking** — Real-time progress with detailed logging
- 🔧 **Configurable** — Flexible configuration with JSON/YAML support

## Schema Bundling with Redocly

The AutoSync CLI automatically bundles OpenAPI schemas using [@redocly/cli](https://redocly.com/docs/cli/commands/bundle) before passing them to the OpenAPI generator. This resolves common `$ref` issues that can cause generation failures.

### How it works:

1. **Automatic Bundling**: When using the OpenAPI generator, schemas are automatically bundled using `redocly bundle`
2. **Flattened Output**: All `$ref` references are resolved into a single, flat schema file
3. **Fallback Support**: If bundling fails, the original schema file is used as fallback
4. **Transparent**: Works automatically without any user configuration needed

---

## 📦 Installation

```bash
# Recommended
bunx @fsco/autosync init

# Or globally
bun add -g @fsco/autosync
```

_NPM/Yarn supported too:_

```bash
npm install -g @fsco/autosync
npx @fsco/autosync init
```

---

## ⚡ Quick Start

```bash
# 1. Init config
fsco-autosync init

# 2. Start watch mode
fsco-autosync watch

# 3. Run one-time sync
fsco-autosync sync
```

---

## 🔧 Configuration (`autosync.json`)

```json
{
  "exclude": ["*.test.*", "node_modules"],
  "folders": [
    {
      "path": "./shared",
      "syncTo": ["./app1/shared", "./app2/shared"]
    }
  ],
  "schemas": [
    {
      "path": "./schema",
      "exportTo": ["./models"],
      "generator": {
        "type": "typescript-fetch",
        "engine": "bun"
      }
    }
  ]
}
```

### Supported Keys

| Key         | Description                                  |
|-------------|----------------------------------------------|
| `folders`   | Sync source → target folders                 |
| `schemas`   | Auto-generate TS models from OpenAPI         |
| `exclude`   | Global and per-folder exclude patterns       |
| `generator` | Choose `"bun"` or `"openapi"` engines        |

---

## 📚 Commands

| Command                 | Description                              |
|-------------------------|------------------------------------------|
| `fsco-autosync init`    | Create config file interactively         |
| `fsco-autosync watch`   | Watch & sync files + generate schemas    |
| `fsco-autosync sync`    | One-time sync/generation                 |
| `fsco-autosync stop`    | Stop Docker-based watcher                |

---

## 🧪 Examples

### Basic Folder Sync

```json
{
  "folders": [
    {
      "path": "./shared/components",
      "syncTo": ["./frontend/src", "./backend/src"]
    }
  ]
}
```

### OpenAPI to TypeScript Models

```json
{
  "schemas": [
    {
      "path": "./api-specs",
      "exportTo": ["./models"],
      "generator": {
        "type": "typescript-fetch",
        "engine": "bun"
      }
    }
  ]
}
```

---

## 🐳 Docker Support

Watch mode uses a bundled Docker image (with Java + OpenAPI CLI). No extra install required:

```bash
fsco-autosync watch
```