🚀 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 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

# Recommended
bunx @fsco/autosync init

# Or globally
bun add -g @fsco/autosync

The CLI runs on Bun (#!/usr/bin/env bun). The package is published to the npm registry for distribution only; install and run it with Bun / bunx as above. Full toolchain notes: docs/bun-toolchain.md.

⚡ Quick Start

# 1. Init config
fsco-autosync init

# 2. Start watch mode
fsco-autosync watch

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

🔧 Configuration (autosync.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 |

For generator.type: "typescript-nestjs" (OpenAPI engine), optional flags are supported:

• dtos (default: true) → generate *.dto.ts files from component schemas plus operation DTOs (XxxQueryDto, XxxParamsDto, XxxBodyDto) when applicable
• zod (default: false) → generate Zod schemas under zod/ (default emitter: Kubb)
• zodCodegen (default: kubb) → choose kubb or orval

📚 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

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

OpenAPI to TypeScript Models

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

🧪 E2E Testing

Run full CLI E2E checks in an isolated workspace:

bun run test:e2e:cli

Run extended E2E including Zod generation:

bun run test:e2e:cli:full

Run the full E2E flow (including Zod) inside Docker:

bun run test:e2e:docker

The E2E scenario validates:

• CLI startup/help
• init --schemas
• sync --local --fresh for OpenAPI NestJS generation
• default DTO generation and naming (adminCorridor.dto.ts)
• single DTO class per schema with readOnly / writeOnly reflected in @ApiProperty
• operation DTO generation for query/path/body (XxxQueryDto, XxxParamsDto, XxxBodyDto)
• optional Zod generation when zod: true under zod/ (enabled in test:e2e:cli:full)

🐳 Docker Support

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

fsco-autosync watch

🧪 Manual Consumer Validation (Local Link)

For real-world validation in another workspace, use local linking (not part of automated repo tests):

# In this repo
bun dev:link

# In your consumer workspace
bun link @fsco/autosync
bun run fsco-autosync sync --progress

Use the consumer workspace autosync.json as the source of truth for schema and output paths. To restore registry package behavior later:

bun unlink @fsco/autosync