🚀 Mecra SSG Publisher

Brotli ve Gzip destekli, çoklu Nginx sunuculara otomatik SSG dağıtımı yapan profesyonel Node.js aracı. Diferansiyel senkronizasyon ile sadece değişen dosyaları deploy eder.

✨ Özellikler

• 🔄 Diferansiyel Sync: Sadece değişen dosyaları deploy eder
• 🗜️ Otomatik Sıkıştırma: Gzip ve Brotli desteği
• 🌐 Multi-Server: Birden fazla sunucuya paralel deployment
• 📦 Single Page & Directory: Hem tek sayfa hem de klasör publish
• � Nginx Site Yönetimi: Site ekleme, silme ve listeleme
• �🔒 Güvenli: SSH key desteği ve doğru dosya izinleri
• 📊 Detaylı Loglama: Debug, info, warn, error seviyeleri
• ⚡ Performanslı: Async/parallel işlemler
• 🛠️ Type-Safe: Full TypeScript desteği

📦 Kurulum

# NPM ile
npm install @ugursahinkaya/ssg-publisher

# PNPM ile
pnpm add @ugursahinkaya/ssg-publisher

# Yarn ile
yarn add @ugursahinkaya/ssg-publisher

🔧 Yapılandırma

Proje kök dizininde .env dosyası oluşturun:

# Gerekli
NGINX_SERVERS=server1,server2,server3
NGINX_ROOT_DIR=/var/www

# Opsiyonel
SSH_KEY_PATH=~/.ssh/deploy_key
LOG_LEVEL=info

Ortam Değişkenleri

| Değişken | Zorunlu | Açıklama | Örnek | |----------|---------|----------|-------| | NGINX_SERVERS | ✅ | Virgülle ayrılmış sunucu listesi | server1,server2 | | NGINX_ROOT_DIR | ✅ | Nginx root dizini | /var/www | | SSH_KEY_PATH | ❌ | SSH private key yolu | ~/.ssh/id_rsa | | LOG_LEVEL | ❌ | Log seviyesi | debug, info, warn, error |

🎯 Kullanım

CLI Kullanımı

# Tek sayfa publish
mecra-ssg publish page https://example.com/about

# Hostname override ile
mecra-ssg publish page https://example.com/about custom.domain.com

# Klasör publish (diferansiyel sync)
# İlk parametre: domain/path (nginx'te nereye: /var/www/example.com/lib)
# İkinci parametre: lokal dizin (deploy edilecek dosyalar: ./dist)
mecra-ssg publish dir example.com ./dist
mecra-ssg publish dir example.com/lib ./my-lib

# Sayfa silme (URL-based, klasör siler)
mecra-ssg delete page https://example.com/old-page

# Dosya silme (path-based)
mecra-ssg delete file example.com/old-file.html

# Klasör silme (path-based)
mecra-ssg delete dir example.com/old-lib

# Nginx site yönetimi
mecra-ssg site add example.com /var/www/example.com
mecra-ssg site remove example.com
mecra-ssg site list

# Yardım
mecra-ssg --help

Programatik Kullanım

import { useSSGPublisher } from '@ugursahinkaya/ssg-publisher';

// Publisher instance oluştur
const publisher = useSSGPublisher();

// Tek sayfa publish
const pageResult = await publisher.publishPage(
  'https://example.com/about'
);
console.log(`✅ ${pageResult.message}`);

// Klasör publish - lokal dizini nginx'e deploy eder
const dirResult = await publisher.publishDir(
  'example.com',    // Domain/path → /var/www/example.com/
  './dist'          // Lokal dizin → deploy edilecek dosyalar
);

// Subdirectory'ye deploy
await publisher.publishDir(
  'example.com/lib',  // → /var/www/example.com/lib/
  './my-lib'
);
console.log(`📦 ${dirResult.filesProcessed} dosya işlendi`);

// Sayfa silme
const deleteResult = await publisher.deletePage(
  'https://example.com/old-page'
);
console.log(`🗑️ ${deleteResult.message}`);

// Dosya silme
await publisher.deleteFile('example.com/old-file.html');

// Klasör silme
await publisher.deleteDir('example.com/old-lib');

// Nginx site yönetimi
await publisher.addSite({
  serverName: 'example.com',
  rootDir: '/var/www/example.com',
  sslCert: '/etc/nginx/ssl/cert.crt',
  sslKey: '/etc/nginx/ssl/key.key'
});

await publisher.removeSite('example.com');

const sites = await publisher.listSites('server1');
console.log('Sites:', sites.sites);

Özel Yapılandırma

import { useSSGPublisher } from '@ugursahinkaya/ssg-publisher';

const publisher = useSSGPublisher({
  serverNames: ['custom-server1', 'custom-server2'],
  nginxRootDir: '/custom/path',
  sshKeyPath: '/path/to/key',
  logLevel: 'debug'
});

await publisher.publishPage('https://example.com/page');

Hata Yönetimi

import { 
  useSSGPublisher, 
  ValidationError,
  NetworkError,
  SSHError,
  ConfigurationError
} from '@ugursahinkaya/ssg-publisher';

try {
  const publisher = useSSGPublisher();
  await publisher.publishPage('https://example.com');
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Geçersiz parametre:', error.message);
  } else if (error instanceof NetworkError) {
    console.error('Ağ hatası:', error.message, error.statusCode);
  } else if (error instanceof SSHError) {
    console.error('SSH hatası:', error.message, error.server);
  } else if (error instanceof ConfigurationError) {
    console.error('Yapılandırma hatası:', error.message);
  }
}

🏗️ Geliştirme

# Bağımlılıkları yükle
pnpm install

# Build
pnpm build

# Watch mode
pnpm build --watch

# Temizlik
rm -rf dist

� Proje Yapısı

mecra/
├── bin/
│   └── mecra-ssg.ts          # CLI entry point
├── src/
│   ├── index.ts              # Ana export
│   ├── config.ts             # Yapılandırma
│   ├── constants/
│   │   └── index.ts          # Sabitler
│   ├── core/
│   │   ├── publisher-page.ts # Sayfa publisher
│   │   ├── publisher-dir.ts  # Klasör publisher
│   │   ├── delete-page.ts    # Sayfa silme
│   │   ├── add-site.ts       # Site ekleme
│   │   ├── remove-site.ts    # Site silme
│   │   └── list-sites.ts     # Site listeleme
│   ├── errors/
│   │   └── index.ts          # Özel hata tipleri
│   ├── types/
│   │   └── index.ts          # TypeScript tipleri
│   └── utils/
│       ├── compress.ts       # Sıkıştırma
│       ├── fs-utils.ts       # Dosya işlemleri
│       ├── hash.ts           # Hash hesaplama
│       ├── logger.ts         # Loglama
│       ├── path-utils.ts     # Path işlemleri
│       └── ssh.ts            # SSH/SCP işlemleri
├── build.config.ts           # Build yapılandırması
├── tsconfig.json             # TypeScript yapılandırması
└── package.json

🔍 Nasıl Çalışır?

Single Page Publish

1. URL'den HTML içeriği fetch edilir
2. Geçici dizine yazılır
3. Gzip ve Brotli ile sıkıştırılır
4. Tüm sunuculara paralel olarak kopyalanır
5. Doğru izinler ayarlanır

Directory Publish (Diferansiyel)

1. Local dosyaların hash'leri hesaplanır
2. Her sunucudaki remote dosyaların hash'leri alınır
3. Fark analizi yapılır (eklenecek, güncellenecek, silinecek)
4. Sadece değişen dosyalar deploy edilir
5. Artık dosyalar silinir

🛡️ Güvenlik

• SSH key-based authentication desteği
• Proper file permissions (640 for files, 750 for dirs)
• Owner/group management (deploy:www-data)
• Input validation ve sanitization
• Error handling ve logging

📊 Performance

• Paralel sunucu işlemleri
• Diferansiyel sync (sadece değişenler)
• Async/await pattern
• Stream-based işlemler
• Efficient hashing

🤝 Katkıda Bulunma

1. Fork yapın
2. Feature branch oluşturun (git checkout -b feature/amazing)
3. Commit yapın (git commit -m 'Add amazing feature')
4. Push yapın (git push origin feature/amazing)
5. Pull Request oluşturun

📄 Lisans

MIT

👤 Yazar

Uğur Şahinkaya

• GitHub: @ugursahinkaya

🙏 Teşekkürler

Bu proje SSG deployment süreçlerini otomatikleştirmek için geliştirilmiştir.