@habityzer/db-sync-tool 1.0.3

package/src/utils/backup-validate.js

@@ -0,0 +1,78 @@
+import { createReadStream } from 'node:fs';
+import { Writable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createGunzip } from 'node:zlib';
+import { BackupError } from './errors.js';
+
+/**
+ * @param {Buffer} buf
+ */
+function looksLikeSql(buf) {
+  const s = buf.toString('utf8', 0, Math.min(buf.length, 8192)).toLowerCase();
+  return (
+    s.includes('create ') ||
+    s.includes('insert ') ||
+    s.includes('--') ||
+    s.includes('set ') ||
+    s.includes('copy ') ||
+    s.includes('/*!') ||
+    s.includes('drop ')
+  );
+}
+
+/**
+ * @param {string} filePath
+ * @param {boolean} isGzip
+ */
+export async function validateBackupFile(filePath, isGzip) {
+  if (isGzip) {
+    const rs = createReadStream(filePath);
+    const gunzip = createGunzip();
+    const sink = new Writable({
+      write(_chunk, _enc, cb) {
+        cb();
+      },
+    });
+    try {
+      await pipeline(rs, gunzip, sink);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new BackupError('Not a valid SQL backup', `File appears corrupted or not gzip: ${msg}`);
+    }
+    return;
+  }
+
+  const first = await readMaxBytesFromPath(filePath, 65536);
+  if (first.length === 0) {
+    throw new BackupError('Not a valid SQL backup', 'File is empty');
+  }
+  if (!looksLikeSql(first)) {
+    throw new BackupError(
+      'Not a valid SQL backup',
+      'File does not look like a SQL dump (missing common SQL patterns)'
+    );
+  }
+}
+
+/**
+ * @param {string} filePath
+ * @param {number} max
+ */
+async function readMaxBytesFromPath(filePath, max) {
+  const rs = createReadStream(filePath);
+  /** @type {Buffer[]} */
+  const chunks = [];
+  let total = 0;
+  try {
+    for await (const chunk of rs) {
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      chunks.push(buf);
+      total += buf.length;
+      if (total >= max) break;
+    }
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new BackupError('Not a valid SQL backup', msg);
+  }
+  return Buffer.concat(chunks);
+}

package/src/utils/compression.js

@@ -0,0 +1,25 @@
+import { createGzip, createGunzip } from 'node:zlib';
+import { PassThrough } from 'node:stream';
+
+/**
+ * @param {boolean} compress
+ * @param {number} level 1-9
+ * @returns {import('node:stream').Transform}
+ */
+export function createCompressStream(compress, level = 6) {
+  if (!compress) {
+    return new PassThrough();
+  }
+  const lv = Math.min(9, Math.max(1, level));
+  return createGzip({ level: lv });
+}
+
+/**
+ * @param {boolean} isGzip
+ */
+export function createDecompressStream(isGzip) {
+  if (!isGzip) {
+    return new PassThrough();
+  }
+  return createGunzip();
+}

package/src/utils/config-loader.js

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const DEFAULT_NAMES = ['.db-sync.json', '.db-syncconfig.json'];
+
+/**
+ * @typedef {object} DbSyncConfig
+ * @property {string} [backupDir]
+ * @property {boolean} [compress]
+ * @property {number} [compressLevel]
+ * @property {number} [keepLast]
+ * @property {string} [timestampFormat]
+ */
+
+/**
+ * Deep merge plain objects (shallow per key).
+ * @param {Record<string, unknown>} base
+ * @param {Record<string, unknown>} over
+ */
+function merge(base, over) {
+  const out = { ...base };
+  for (const [k, v] of Object.entries(over)) {
+    if (v !== undefined && v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      out[k] = merge(
+        typeof base[k] === 'object' && base[k] !== null ? /** @type {Record<string, unknown>} */ (base[k]) : {},
+        /** @type {Record<string, unknown>} */ (v)
+      );
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+/**
+ * Find first existing config file in cwd.
+ * @param {string} [cwd]
+ */
+export function discoverConfigPath(cwd = process.cwd()) {
+  for (const name of DEFAULT_NAMES) {
+    const p = resolve(cwd, name);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * @param {string} filePath
+ * @returns {DbSyncConfig}
+ */
+export function readConfigFile(filePath) {
+  const raw = readFileSync(filePath, 'utf8');
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Load optional config: explicit path or first default in cwd.
+ * @param {{ configPath?: string, cwd?: string }} opts
+ * @returns {{ config: DbSyncConfig, path: string | null }}
+ */
+export function loadConfig(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const explicit = opts.configPath ? resolve(cwd, opts.configPath) : null;
+  const path = explicit && existsSync(explicit) ? explicit : discoverConfigPath(cwd);
+  if (!path) {
+    return { config: {}, path: null };
+  }
+  return { config: readConfigFile(path), path };
+}
+
+/**
+ * Merge CLI overrides into config-derived defaults.
+ * @param {DbSyncConfig} fileConfig
+ * @param {Record<string, unknown>} cliOverrides
+ */
+export function mergeWithCli(fileConfig, cliOverrides) {
+  return merge(
+    {
+      backupDir: './backups',
+      compress: true,
+      compressLevel: 6,
+      keepLast: 30,
+      timestampFormat: 'YYYYMMDD_HHMMSS',
+      ...fileConfig,
+    },
+    cliOverrides
+  );
+}

package/src/utils/env-loader.js

@@ -0,0 +1,45 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import dotenv from 'dotenv';
+import { ConfigError } from './errors.js';
+
+/**
+ * Load .env from cwd-relative path. Does not override existing process.env by default.
+ * @param {string} [envFilePath]
+ * @param {{ override?: boolean }} [opts]
+ */
+export function loadEnvFile(envFilePath = '.env', opts = {}) {
+  const path = resolve(process.cwd(), envFilePath);
+  if (!existsSync(path)) {
+    throw new ConfigError(
+      'No .env file found',
+      `Create ${envFilePath} with DATABASE_URL or pass --env-file <path>`
+    );
+  }
+  const raw = readFileSync(path, 'utf8');
+  const parsed = dotenv.parse(raw);
+  const override = opts.override ?? false;
+  for (const [k, v] of Object.entries(parsed)) {
+    if (override || process.env[k] === undefined) {
+      process.env[k] = v;
+    }
+  }
+  return path;
+}
+
+/**
+ * Try to load .env without throwing (for list/info/clean that may not need DB).
+ * @param {string} envFilePath
+ */
+export function tryLoadEnvFile(envFilePath = '.env') {
+  const path = resolve(process.cwd(), envFilePath);
+  if (!existsSync(path)) return null;
+  const raw = readFileSync(path, 'utf8');
+  const parsed = dotenv.parse(raw);
+  for (const [k, v] of Object.entries(parsed)) {
+    if (process.env[k] === undefined) {
+      process.env[k] = v;
+    }
+  }
+  return path;
+}

package/src/utils/errors.js

@@ -0,0 +1,45 @@
+/**
+ * Application errors with optional suggested fixes for CLI output.
+ */
+export class AppError extends Error {
+  /**
+   * @param {string} message
+   * @param {object} [opts]
+   * @param {string} [opts.suggestion]
+   * @param {number} [opts.exitCode]
+   */
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = 'AppError';
+    this.suggestion = opts.suggestion;
+    this.exitCode = opts.exitCode ?? 1;
+  }
+}
+
+export class ConfigError extends AppError {
+  constructor(message, suggestion) {
+    super(message, { suggestion });
+    this.name = 'ConfigError';
+  }
+}
+
+export class ConnectionError extends AppError {
+  constructor(message, suggestion) {
+    super(message, { suggestion });
+    this.name = 'ConnectionError';
+  }
+}
+
+export class FileSystemError extends AppError {
+  constructor(message, suggestion) {
+    super(message, { suggestion });
+    this.name = 'FileSystemError';
+  }
+}
+
+export class BackupError extends AppError {
+  constructor(message, suggestion) {
+    super(message, { suggestion });
+    this.name = 'BackupError';
+  }
+}

package/src/utils/process.js

@@ -0,0 +1,79 @@
+import { spawn } from 'node:child_process';
+import { AppError } from './errors.js';
+
+/**
+ * @typedef {object} SpawnStreamOptions
+ * @property {NodeJS.ReadableStream} [stdin]
+ * @property {NodeJS.WritableStream} [stdout]
+ * @property {NodeJS.WritableStream} [stderr]
+ * @property {Record<string, string>} [env]
+ * @property {string} [cwd]
+ */
+
+/**
+ * Spawn a process; pipe stdin/stdout if provided. Resolves on exit 0.
+ * @param {string} command
+ * @param {string[]} args
+ * @param {SpawnStreamOptions} opts
+ * @returns {Promise<{ code: number, stderr: string }>}
+ */
+export function spawnProcess(command, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, ...opts.env },
+      cwd: opts.cwd,
+    });
+
+    let stderr = '';
+    child.stderr?.on('data', (c) => {
+      stderr += c.toString();
+    });
+
+    if (opts.stdin) {
+      opts.stdin.pipe(child.stdin);
+      opts.stdin.on('error', (e) => {
+        child.stdin?.destroy();
+        reject(e);
+      });
+    } else {
+      child.stdin?.end();
+    }
+
+    if (opts.stdout) {
+      child.stdout.pipe(opts.stdout);
+    }
+
+    child.on('error', reject);
+    child.on('close', (code) => {
+      resolve({ code: code ?? 0, stderr });
+    });
+  });
+}
+
+/**
+ * @param {string} command
+ * @param {string[]} args
+ * @param {SpawnStreamOptions} opts
+ */
+export async function spawnProcessOrThrow(command, args, opts = {}) {
+  const { code, stderr } = await spawnProcess(command, args, opts);
+  if (code !== 0) {
+    throw new AppError(`${command} exited with code ${code}`, {
+      suggestion: stderr.trim() || 'Check database client tools are installed and DATABASE_URL is correct',
+    });
+  }
+}
+
+/**
+ * Wait for readable/writable stream end if present.
+ * @param {import('node:stream').Readable | import('node:stream').Writable} stream
+ */
+export async function finishedWrite(stream) {
+  if (!stream || typeof stream.end !== 'function') return;
+  await new Promise((resolve, reject) => {
+    stream.on('finish', resolve);
+    stream.on('error', reject);
+    if ('writableFinished' in stream && stream.writableFinished) resolve(undefined);
+  });
+}

package/src/utils/progress.js

@@ -0,0 +1,115 @@
+import cliProgress from 'cli-progress';
+import chalk from 'chalk';
+import ora from 'ora';
+
+/**
+ * @param {number} bytes
+ */
+export function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 ** 2) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 ** 3) return `${(bytes / 1024 ** 2).toFixed(1)} MB`;
+  return `${(bytes / 1024 ** 3).toFixed(1)} GB`;
+}
+
+/**
+ * Spinner + byte counter when total size is unknown (e.g. pg_dump stream).
+ * @param {string} text
+ * @param {{ verbose?: boolean }} ctx
+ */
+export function createStreamProgress(text, ctx = {}) {
+  if (ctx.verbose) {
+    let bytes = 0;
+    return {
+      start() {},
+      /** @param {number} n */
+      increment(n) {
+        bytes += n;
+      },
+      succeed(finalText) {
+        if (finalText) console.log(finalText);
+      },
+      fail() {},
+      getBytes: () => bytes,
+    };
+  }
+
+  const spin = ora({ text, spinner: 'dots' }).start();
+  let bytes = 0;
+
+  return {
+    start() {},
+    /** @param {number} n */
+    increment(n) {
+      bytes += n;
+      spin.text = `${text} ${formatBytes(bytes)}`;
+    },
+    succeed(finalText) {
+      spin.succeed(finalText ?? `${text} ${formatBytes(bytes)}`);
+    },
+    fail(msg) {
+      spin.fail(msg);
+    },
+    getBytes: () => bytes,
+  };
+}
+
+/**
+ * Progress bar when total bytes known (e.g. restore from file).
+ * @param {string} label
+ * @param {number} totalBytes
+ * @param {{ verbose?: boolean }} ctx
+ */
+export function createFileProgressBar(label, totalBytes, ctx = {}) {
+  if (ctx.verbose || totalBytes <= 0) {
+    let transferred = 0;
+    return {
+      start() {},
+      /** @param {number} n */
+      increment(n) {
+        transferred += n;
+      },
+      stop() {},
+      getTransferred() {
+        return transferred;
+      },
+    };
+  }
+
+  const bar = new cliProgress.SingleBar(
+    {
+      format: `${label} |${chalk.cyan('{bar}')}| {percentage}% | {transferred} | {duration}s`,
+      barCompleteChar: '\u2588',
+      barIncompleteChar: '\u2591',
+      hideCursor: true,
+    },
+    cliProgress.Presets.shades_classic
+  );
+
+  let transferred = 0;
+  const startTime = Date.now();
+
+  return {
+    start() {
+      bar.start(totalBytes, 0, {
+        transferred: '0 B',
+        duration: '0.0',
+      });
+    },
+    /** @param {number} n */
+    increment(n) {
+      transferred += n;
+      const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+      bar.update(transferred, {
+        transferred: formatBytes(transferred),
+        duration: elapsed,
+      });
+    },
+    stop() {
+      bar.stop();
+    },
+    getTransferred() {
+      return transferred;
+    },
+  };
+}

package/src/utils/prompt.js

@@ -0,0 +1,22 @@
+import * as readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+
+/**
+ * @param {string} question
+ */
+export async function ask(question) {
+  const rl = readline.createInterface({ input, output });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * @param {string} question
+ */
+export async function confirm(question) {
+  const a = (await ask(question)).trim().toLowerCase();
+  return a === 'y' || a === 'yes';
+}

package/src/utils/retention.js

@@ -0,0 +1,32 @@
+/**
+ * @typedef {import('./backup-scanner.js').BackupEntry} BackupEntry
+ */
+
+/**
+ * Union keep: keep if in newest `keepLast` OR newer than `keepDays` cutoff.
+ * @param {BackupEntry[]} sortedNewestFirst
+ * @param {{ keepLast?: number, keepDays?: number, now?: number }} opts
+ * @returns {{ keep: BackupEntry[], remove: BackupEntry[] }}
+ */
+export function planRetention(sortedNewestFirst, opts) {
+  const now = opts.now ?? Date.now();
+  const keepLast = opts.keepLast;
+  const keepDays = opts.keepDays;
+  const cutoff = keepDays != null ? now - keepDays * 86400000 : null;
+
+  /** @type {BackupEntry[]} */
+  const keep = [];
+  /** @type {BackupEntry[]} */
+  const remove = [];
+
+  sortedNewestFirst.forEach((entry, index) => {
+    const t = (entry.parsedDate ?? entry.mtime).getTime();
+    let kept = false;
+    if (keepLast != null && index < keepLast) kept = true;
+    if (cutoff != null && t >= cutoff) kept = true;
+    if (kept) keep.push(entry);
+    else remove.push(entry);
+  });
+
+  return { keep, remove };
+}

package/src/utils/ui.js

@@ -0,0 +1,63 @@
+import chalk from 'chalk';
+
+/** @typedef {{ verbose?: boolean }} LogContext */
+
+/**
+ * @param {LogContext} ctx
+ * @param {...unknown} args
+ */
+export function debug(ctx, ...args) {
+  if (ctx?.verbose) {
+    console.error(chalk.gray('[debug]'), ...args);
+  }
+}
+
+export const icons = {
+  ok: '✅',
+  err: '❌',
+  warn: '⚠️',
+  pkg: '📦',
+  save: '💾',
+  link: '🔗',
+  chart: '📊',
+  empty: '📭',
+  spin: '🔄',
+};
+
+/**
+ * @param {string} msg
+ */
+export function success(msg) {
+  console.log(`${icons.ok} ${msg}`);
+}
+
+/**
+ * @param {string} msg
+ */
+export function errorLine(msg) {
+  console.error(`${icons.err} ${msg}`);
+}
+
+/**
+ * @param {string} msg
+ */
+export function warnLine(msg) {
+  console.error(`${icons.warn} ${msg}`);
+}
+
+/**
+ * @param {string} msg
+ */
+export function infoLine(msg) {
+  console.log(msg);
+}
+
+/**
+ * @param {import('./errors.js').AppError} err
+ */
+export function printErrorWithSuggestion(err) {
+  errorLine(err.message);
+  if (err.suggestion) {
+    console.error(chalk.dim(`   ${err.suggestion}`));
+  }
+}