@abdess76/i18nkit 1.0.3 → 1.0.5

package/bin/core/applier.js

@@ -8,7 +8,7 @@
 
 const fs = require('./fs-adapter');
 const path = require('path');
-const { createBackup } = require('./backup');
+const { withBackup } = require('./backup');
 const {
   groupFindingsByFile,
   confirmFileModifications,
@@ -70,13 +70,12 @@ function buildFileResult(ctx) {
 }
 
 function processFileReplacements(relativeFile, fileFindings, opts) {
-  const { srcDir, backupDir, backup = true, dryRun = false, verbose = false, adapter } = opts;
+  const { srcDir, verbose = false, adapter } = opts;
   const filePath = path.join(srcDir, relativeFile);
   const originalContent = loadFileForReplacement(filePath, relativeFile, verbose);
   if (!originalContent) {
     return null;
   }
-  createBackup(filePath, backupDir, { enabled: backup, dryRun });
   const { content: replaced, count } = applyReplacementsToContent(
     originalContent,
     fileFindings,
@@ -125,6 +124,90 @@ function processAllFiles(findingsByFile, opts) {
   return { totalFiles, totalReplacements, modifiedFiles };
 }
 
+function getFilesToBackup(findingsByFile, opts) {
+  const { srcDir } = opts;
+  const files = [];
+  for (const [relativeFile] of findingsByFile) {
+    const filePath = path.join(srcDir, relativeFile);
+    if (fs.existsSync(filePath)) {
+      files.push(filePath);
+    }
+  }
+  return files;
+}
+
+function backupFilesForSession(filesToBackup, sessionHelpers) {
+  for (const filePath of filesToBackup) {
+    if (sessionHelpers?.backupFile) {
+      sessionHelpers.backupFile(filePath);
+    }
+  }
+}
+
+function saveReportIfNeeded(sessionHelpers, reportPath) {
+  if (reportPath && sessionHelpers?.saveReport) {
+    sessionHelpers.saveReport(reportPath);
+  }
+}
+
+function transitionSessionState(sessionHelpers) {
+  if (sessionHelpers?.markReady) {
+    sessionHelpers.markReady();
+  }
+  if (sessionHelpers?.beginModifications) {
+    sessionHelpers.beginModifications();
+  }
+}
+
+function prepareSession(sessionHelpers, reportPath) {
+  saveReportIfNeeded(sessionHelpers, reportPath);
+  transitionSessionState(sessionHelpers);
+}
+
+function createApplyExecutor(ctx) {
+  const { filesToBackup, reportPath, findingsByFile, opts } = ctx;
+  return sessionHelpers => {
+    backupFilesForSession(filesToBackup, sessionHelpers);
+    prepareSession(sessionHelpers, reportPath);
+    const results = processAllFiles(findingsByFile, opts);
+    logApplyResults(results, opts);
+    return { success: true, ...results };
+  };
+}
+
+function logApplyHeader(log) {
+  log('Auto-Apply Translations');
+  log('-'.repeat(50));
+}
+
+function buildApplyContext(findingsByFile, opts) {
+  const cwd = process.cwd();
+  const { reportDir } = opts;
+  const filesToBackup = getFilesToBackup(findingsByFile, opts);
+  const reportPath = reportDir ? path.join(reportDir, 'report.json') : null;
+  return { cwd, filesToBackup, reportPath, findingsByFile, opts };
+}
+
+async function confirmAndPrepare(findings, opts) {
+  const { log = console.log, interactive = false } = opts;
+  logApplyHeader(log);
+  const findingsByFile = groupFindingsByFile(findings);
+  const shouldProceed = await confirmFileModifications(findingsByFile, interactive, log);
+  return shouldProceed ? findingsByFile : null;
+}
+
+function executeApplyWithBackup(findingsByFile, opts) {
+  const { log = console.log, backup = true, dryRun = false } = opts;
+  const ctx = buildApplyContext(findingsByFile, opts);
+  const executeApply = createApplyExecutor(ctx);
+  return withBackup({
+    cwd: ctx.cwd,
+    command: 'apply',
+    operation: executeApply,
+    options: { log, backup, dryRun },
+  });
+}
+
 /**
  * Applies translation replacements from findings array
  * @param {Finding[]} findings
@@ -132,17 +215,10 @@ function processAllFiles(findingsByFile, opts) {
  * @returns {Promise<ApplyResult>}
  */
 async function applyFindings(findings, opts = {}) {
-  const { log = console.log, interactive = false } = opts;
-  log('Auto-Apply Translations');
-  log('-'.repeat(50));
-  const findingsByFile = groupFindingsByFile(findings);
-  const shouldProceed = await confirmFileModifications(findingsByFile, interactive, log);
-  if (!shouldProceed) {
-    return { success: false, aborted: true };
-  }
-  const results = processAllFiles(findingsByFile, opts);
-  logApplyResults(results, opts);
-  return { success: true, ...results };
+  const findingsByFile = await confirmAndPrepare(findings, opts);
+  return findingsByFile ?
+      executeApplyWithBackup(findingsByFile, opts)
+    : { success: false, aborted: true };
 }
 
 /**

package/bin/core/args.js

@@ -98,6 +98,11 @@ const COMMAND_ALIASES = {
   '--find-orphans': 'find-orphans',
   '--check-sync': 'check-sync',
   '--watch': 'watch',
+  '--list-backups': 'backup',
+  '--restore': 'backup',
+  '--cleanup-backups': 'backup',
+  '--backup-info': 'backup',
+  '--init-backups': 'backup',
 };
 
 const POSITIONAL_COMMANDS = [
@@ -107,6 +112,15 @@ const POSITIONAL_COMMANDS = [
   'apply',
   'watch',
   'extract',
+  'backup',
+];
+
+const BACKUP_FLAGS = [
+  '--list-backups',
+  '--restore',
+  '--cleanup-backups',
+  '--backup-info',
+  '--init-backups',
 ];
 
 function detectFromFlags(args) {
@@ -116,6 +130,9 @@ function detectFromFlags(args) {
   if (args.some(a => a.startsWith('--apply'))) {
     return 'apply';
   }
+  if (args.some(a => BACKUP_FLAGS.includes(a))) {
+    return 'backup';
+  }
   const flagCmd = args.find(a => COMMAND_ALIASES[a]);
   return flagCmd ? COMMAND_ALIASES[flagCmd] : null;
 }

package/bin/core/backup/cleanup.js

@@ -0,0 +1,176 @@
+'use strict';
+
+/**
+ * @fileoverview Backup session cleanup and retention management.
+ * @module backup/cleanup
+ */
+
+const { Session, parseSessionId } = require('./session');
+const { removeDirSync } = require('./file-ops');
+const { DEFAULT_CONFIG, getSessionDir, SessionStatus } = require('./constants');
+
+/**
+ * Returns session age in days
+ * @param {string} sessionId
+ * @returns {number}
+ */
+function getSessionAge(sessionId) {
+  const parsed = parseSessionId(sessionId);
+  if (!parsed) {
+    return Infinity;
+  }
+  const now = new Date();
+  const diff = now - parsed.timestamp;
+  return Math.floor(diff / (1000 * 60 * 60 * 24));
+}
+
+function shouldKeepSession(session) {
+  return (
+    session.status === SessionStatus.IN_PROGRESS || session.status === SessionStatus.BACKING_UP
+  );
+}
+
+function isWithinLimits(index, age, config) {
+  return index < config.maxSessions && age <= config.maxAgeDays;
+}
+
+function categorizeSession(session, index, config) {
+  const age = getSessionAge(session.id);
+  return { session, keep: isWithinLimits(index, age, config) };
+}
+
+/**
+ * @param {Object[]} sessions
+ * @param {Object} config
+ * @returns {{keep: Object[], delete: Object[]}}
+ */
+function selectSessionsForCleanup(sessions, config) {
+  const protectedSessions = sessions.filter(shouldKeepSession);
+  const cleanableSessions = sessions.filter(s => !shouldKeepSession(s));
+  const categorized = cleanableSessions.map((s, i) => categorizeSession(s, i, config));
+  const toKeep = categorized.filter(c => c.keep).map(c => c.session);
+  const toDelete = categorized.filter(c => !c.keep).map(c => c.session);
+  return { keep: [...protectedSessions, ...toKeep], delete: toDelete };
+}
+
+function logVerbose(verbose, log, message) {
+  if (verbose) {
+    log(message);
+  }
+}
+
+function deleteSession(sessionDir, sessionId, ctx) {
+  const { dryRun, verbose, log } = ctx;
+  if (dryRun) {
+    log(`Would delete: ${sessionId}`);
+    return false;
+  }
+  try {
+    removeDirSync(sessionDir);
+    logVerbose(verbose, log, `Deleted: ${sessionId}`);
+    return true;
+  } catch (err) {
+    logVerbose(verbose, log, `Failed to delete ${sessionId}: ${err.message}`);
+    return false;
+  }
+}
+
+function processDeletions(cwd, toDelete, ctx) {
+  return toDelete.map(session => {
+    const sessionDir = getSessionDir(cwd, session.id);
+    return deleteSession(sessionDir, session.id, ctx);
+  });
+}
+
+function handleEmptySessions(verbose, log) {
+  logVerbose(verbose, log, 'No backup sessions found');
+  return { deleted: 0, kept: 0 };
+}
+
+function handleNoDeletions(keep, verbose, log) {
+  logVerbose(verbose, log, `Keeping all ${keep.length} sessions`);
+  return { deleted: 0, kept: keep.length };
+}
+
+function executeCleanup(ctx) {
+  const { cwd, sessions, config, dryRun, verbose, log } = ctx;
+  const { keep, delete: toDelete } = selectSessionsForCleanup(sessions, config);
+  if (toDelete.length === 0) {
+    return handleNoDeletions(keep, verbose, log);
+  }
+  processDeletions(cwd, toDelete, { dryRun, verbose, log });
+  return { deleted: dryRun ? 0 : toDelete.length, kept: keep.length };
+}
+
+function loadSessions(cwd) {
+  const sessions = Session.listAll(cwd);
+  return sessions.length === 0 ? null : sessions;
+}
+
+function buildCleanupContext(cwd, options) {
+  const config = { ...DEFAULT_CONFIG, ...options };
+  const { dryRun = false, verbose = false, log = console.log } = options;
+  return { cwd, config, dryRun, verbose, log };
+}
+
+/**
+ * Removes sessions exceeding retention limits
+ * @param {string} cwd
+ * @param {Object} [options]
+ * @returns {{deleted: number, kept: number}}
+ */
+function cleanupOldSessions(cwd, options = {}) {
+  const ctx = buildCleanupContext(cwd, options);
+  const sessions = loadSessions(cwd);
+  if (!sessions) {
+    return handleEmptySessions(ctx.verbose, ctx.log);
+  }
+  return executeCleanup({ ...ctx, sessions });
+}
+
+function mapSessionForPreview(session) {
+  return {
+    id: session.id,
+    age: getSessionAge(session.id),
+    status: session.status,
+    fileCount: session.fileCount,
+  };
+}
+
+/**
+ * Returns cleanup preview without executing
+ * @param {string} cwd
+ * @param {Object} [options]
+ * @returns {{sessions: Object[], toDelete: Object[], toKeep: Object[]}}
+ */
+function getCleanupPreview(cwd, options = {}) {
+  const config = { ...DEFAULT_CONFIG, ...options };
+  const sessions = Session.listAll(cwd);
+  if (sessions.length === 0) {
+    return { sessions: [], toDelete: [], toKeep: [] };
+  }
+  const { keep, delete: toDelete } = selectSessionsForCleanup(sessions, config);
+  return {
+    sessions,
+    toDelete: toDelete.map(mapSessionForPreview),
+    toKeep: keep.map(mapSessionForPreview),
+  };
+}
+
+/**
+ * @param {string} cwd
+ * @param {Object} config
+ * @returns {{deleted: number, kept: number}|null}
+ */
+function autoCleanupIfEnabled(cwd, config) {
+  if (!config.autoCleanup) {
+    return null;
+  }
+  return cleanupOldSessions(cwd, { ...config, verbose: false });
+}
+
+module.exports = {
+  cleanupOldSessions,
+  getCleanupPreview,
+  autoCleanupIfEnabled,
+};

package/bin/core/backup/constants.js

@@ -0,0 +1,114 @@
+'use strict';
+
+/**
+ * @fileoverview Backup system constants and path utilities.
+ * @module backup/constants
+ */
+
+const path = require('path');
+
+const BACKUP_ROOT = '.i18nkit';
+const BACKUP_DIR = 'backups';
+const LATEST_FILE = 'latest.txt';
+const MANIFEST_FILE = 'manifest.json';
+const STATUS_FILE = '.status';
+const GITIGNORE_FILE = '.gitignore';
+
+const SessionStatus = Object.freeze({
+  PENDING: 'pending',
+  BACKING_UP: 'backing-up',
+  READY: 'ready',
+  IN_PROGRESS: 'in-progress',
+  COMPLETED: 'completed',
+  ROLLED_BACK: 'rolled-back',
+  FAILED: 'failed',
+});
+
+const VALID_TRANSITIONS = Object.freeze({
+  [SessionStatus.PENDING]: [SessionStatus.BACKING_UP, SessionStatus.FAILED],
+  [SessionStatus.BACKING_UP]: [SessionStatus.READY, SessionStatus.FAILED],
+  [SessionStatus.READY]: [SessionStatus.IN_PROGRESS, SessionStatus.FAILED],
+  [SessionStatus.IN_PROGRESS]: [
+    SessionStatus.COMPLETED,
+    SessionStatus.ROLLED_BACK,
+    SessionStatus.FAILED,
+  ],
+  [SessionStatus.COMPLETED]: [],
+  [SessionStatus.ROLLED_BACK]: [],
+  [SessionStatus.FAILED]: [],
+});
+
+const DEFAULT_CONFIG = Object.freeze({
+  maxSessions: 10,
+  maxAgeDays: 30,
+  autoCleanup: true,
+});
+
+/**
+ * @param {string} cwd
+ * @returns {string}
+ */
+function getBackupRoot(cwd) {
+  return path.join(cwd, BACKUP_ROOT);
+}
+
+/**
+ * @param {string} cwd
+ * @returns {string}
+ */
+function getBackupsDir(cwd) {
+  return path.join(cwd, BACKUP_ROOT, BACKUP_DIR);
+}
+
+/**
+ * @param {string} cwd
+ * @returns {string}
+ */
+function getLatestFile(cwd) {
+  return path.join(cwd, BACKUP_ROOT, BACKUP_DIR, LATEST_FILE);
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} sessionId
+ * @returns {string}
+ */
+function getSessionDir(cwd, sessionId) {
+  return path.join(cwd, BACKUP_ROOT, BACKUP_DIR, sessionId);
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} sessionId
+ * @returns {string}
+ */
+function getManifestPath(cwd, sessionId) {
+  return path.join(getSessionDir(cwd, sessionId), MANIFEST_FILE);
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} sessionId
+ * @returns {string}
+ */
+function getStatusPath(cwd, sessionId) {
+  return path.join(getSessionDir(cwd, sessionId), STATUS_FILE);
+}
+
+module.exports = {
+  BACKUP_ROOT,
+  BACKUP_DIR,
+  LATEST_FILE,
+  MANIFEST_FILE,
+  STATUS_FILE,
+  GITIGNORE_FILE,
+  SessionStatus,
+  VALID_TRANSITIONS,
+  DEFAULT_CONFIG,
+  getBackupRoot,
+  getBackupsDir,
+  getLatestFile,
+  getSessionDir,
+  getManifestPath,
+  getStatusPath,
+};

package/bin/core/backup/file-ops.js

@@ -0,0 +1,188 @@
+'use strict';
+
+/**
+ * @fileoverview Atomic file operations for backup system.
+ * @module backup/file-ops
+ */
+
+const fs = require('../fs-adapter');
+const nodeFsSync = require('fs');
+const nodeFsPromises = require('fs').promises;
+const path = require('path');
+const crypto = require('crypto');
+
+function generateTempPath(targetPath) {
+  const rand = crypto.randomBytes(4).toString('hex');
+  return `${targetPath}.${Date.now()}.${rand}.tmp`;
+}
+
+/**
+ * Writes content atomically via temp file + rename
+ * @param {string} targetPath
+ * @param {string} content
+ * @returns {Promise<void>}
+ */
+async function atomicWrite(targetPath, content) {
+  const tempPath = generateTempPath(targetPath);
+  const dir = path.dirname(targetPath);
+  await fs.mkdir(dir, { recursive: true });
+  try {
+    await fs.writeFile(tempPath, content, 'utf-8');
+    await fs.rename(tempPath, targetPath);
+  } catch (err) {
+    try {
+      await fs.unlink(tempPath);
+    } catch {
+      // Cleanup failure is non-critical
+    }
+    throw err;
+  }
+}
+
+/**
+ * @param {string} targetPath
+ * @param {string} content
+ */
+function atomicWriteSync(targetPath, content) {
+  const tempPath = generateTempPath(targetPath);
+  const dir = path.dirname(targetPath);
+  fs.mkdirSync(dir, { recursive: true });
+  try {
+    fs.writeFileSync(tempPath, content, 'utf-8');
+    nodeFsSync.renameSync(tempPath, targetPath);
+  } catch (err) {
+    try {
+      nodeFsSync.unlinkSync(tempPath);
+    } catch {
+      // Cleanup failure is non-critical
+    }
+    throw err;
+  }
+}
+
+/**
+ * Copies file preserving directory structure relative to cwd
+ * @param {string} srcFile
+ * @param {string} destRoot
+ * @param {string} cwd
+ * @returns {Promise<{original: string, backup: string, size: number}>}
+ */
+async function copyFilePreservingStructure(srcFile, destRoot, cwd) {
+  const relativePath = path.relative(cwd, srcFile);
+  const destPath = path.join(destRoot, relativePath);
+  const content = await fs.readFile(srcFile, 'utf-8');
+  await atomicWrite(destPath, content);
+  return {
+    original: relativePath,
+    backup: relativePath,
+    size: Buffer.byteLength(content, 'utf-8'),
+  };
+}
+
+/**
+ * @param {string} srcFile
+ * @param {string} destRoot
+ * @param {string} cwd
+ * @returns {{original: string, backup: string, size: number}}
+ */
+function copyFilePreservingStructureSync(srcFile, destRoot, cwd) {
+  const relativePath = path.relative(cwd, srcFile);
+  const destPath = path.join(destRoot, relativePath);
+  const content = fs.readFileSync(srcFile, 'utf-8');
+  atomicWriteSync(destPath, content);
+  return {
+    original: relativePath,
+    backup: relativePath,
+    size: Buffer.byteLength(content, 'utf-8'),
+  };
+}
+
+/**
+ * @param {string} backupPath
+ * @param {string} originalPath
+ * @returns {Promise<void>}
+ */
+async function restoreFile(backupPath, originalPath, _cwd) {
+  const content = await fs.readFile(backupPath, 'utf-8');
+  await atomicWrite(originalPath, content);
+}
+
+/**
+ * @param {string} backupPath
+ * @param {string} originalPath
+ */
+function restoreFileSync(backupPath, originalPath) {
+  const content = fs.readFileSync(backupPath, 'utf-8');
+  atomicWriteSync(originalPath, content);
+}
+
+/**
+ * @param {string} dirPath
+ * @returns {Promise<void>}
+ */
+async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+/**
+ * @param {string} dirPath
+ */
+function ensureDirSync(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+/**
+ * @param {string} dirPath
+ * @returns {Promise<void>}
+ */
+async function removeDir(dirPath) {
+  await nodeFsPromises.rm(dirPath, { recursive: true, force: true });
+}
+
+/**
+ * @param {string} dirPath
+ */
+function removeDirSync(dirPath) {
+  nodeFsSync.rmSync(dirPath, { recursive: true, force: true });
+}
+
+/**
+ * @param {string} parentDir
+ * @returns {Promise<string[]>}
+ */
+async function listDirs(parentDir) {
+  try {
+    const entries = await fs.readdir(parentDir, { withFileTypes: true });
+    return entries.filter(e => e.isDirectory()).map(e => e.name);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * @param {string} parentDir
+ * @returns {string[]}
+ */
+function listDirsSync(parentDir) {
+  try {
+    const entries = fs.readdirSync(parentDir, { withFileTypes: true });
+    return entries.filter(e => e.isDirectory()).map(e => e.name);
+  } catch {
+    return [];
+  }
+}
+
+module.exports = {
+  atomicWrite,
+  atomicWriteSync,
+  copyFilePreservingStructure,
+  copyFilePreservingStructureSync,
+  restoreFile,
+  restoreFileSync,
+  ensureDir,
+  ensureDirSync,
+  removeDir,
+  removeDirSync,
+  listDirs,
+  listDirsSync,
+};