@abdess76/i18nkit 1.0.3 → 1.0.5

package/bin/core/backup/restore.js

@@ -0,0 +1,216 @@
+'use strict';
+
+/**
+ * @fileoverview Session restoration and rollback operations.
+ * @module backup/restore
+ */
+
+const { Session } = require('./session');
+const { restoreFileSync } = require('./file-ops');
+const { SessionStatus, getSessionDir } = require('./constants');
+const fs = require('../fs-adapter');
+
+function logIfVerbose(verbose, log, message) {
+  if (verbose) {
+    log(message);
+  }
+}
+
+function handleMissingBackup(file, ctx) {
+  logIfVerbose(ctx.verbose, ctx.log, `  Skip (backup missing): ${file.original}`);
+  return { restored: false, skipped: true };
+}
+
+function handleDryRun(file, ctx) {
+  ctx.log(`  Would restore: ${file.original}`);
+  return { restored: true, skipped: false };
+}
+
+function performRestore(file, ctx) {
+  restoreFileSync(file.backup, file.original);
+  logIfVerbose(ctx.verbose, ctx.log, `  Restored: ${file.original}`);
+  return { restored: true, skipped: false };
+}
+
+function restoreFileWithLogging(file, ctx) {
+  if (!fs.existsSync(file.backup)) {
+    return handleMissingBackup(file, ctx);
+  }
+  return ctx.dryRun ? handleDryRun(file, ctx) : performRestore(file, ctx);
+}
+
+function processRestoreFile(file, ctx) {
+  try {
+    return restoreFileWithLogging(file, ctx);
+  } catch (err) {
+    logIfVerbose(ctx.verbose, ctx.log, `  Error restoring ${file.original}: ${err.message}`);
+    return { restored: false, skipped: true };
+  }
+}
+
+function loadSessionOrThrow(cwd, sessionId) {
+  const session = Session.load(cwd, sessionId);
+  if (!session) {
+    throw new Error(`Session not found: ${sessionId}`);
+  }
+  return session;
+}
+
+function countResults(results) {
+  return {
+    restored: results.filter(r => r.restored).length,
+    skipped: results.filter(r => r.skipped).length,
+  };
+}
+
+function executeRestore(files, ctx) {
+  const results = files.map(file => processRestoreFile(file, ctx));
+  return countResults(results);
+}
+
+function loadFilesOrEmpty(cwd, sessionId, log) {
+  const session = loadSessionOrThrow(cwd, sessionId);
+  const files = session.getBackedUpFiles();
+  if (files.length === 0) {
+    log('No files to restore');
+  }
+  return files;
+}
+
+function buildRestoreContext(options) {
+  const { dryRun = false, verbose = false, log = console.log } = options;
+  return { dryRun, verbose, log };
+}
+
+/**
+ * Restores files from a backup session
+ * @param {string} cwd
+ * @param {string} sessionId
+ * @param {Object} [options]
+ * @returns {{restored: number, skipped: number}}
+ */
+function restoreSession(cwd, sessionId, options = {}) {
+  const ctx = buildRestoreContext(options);
+  const files = loadFilesOrEmpty(cwd, sessionId, ctx.log);
+  if (files.length === 0) {
+    return { restored: 0, skipped: 0 };
+  }
+  return executeRestore(files, ctx);
+}
+
+/**
+ * Restores files from the latest backup session
+ * @param {string} cwd
+ * @param {Object} [options]
+ * @returns {{restored: number, skipped: number}}
+ */
+function restoreLatest(cwd, options = {}) {
+  const latestId = Session.getLatestId(cwd);
+  if (!latestId) {
+    throw new Error('No backup sessions found');
+  }
+  return restoreSession(cwd, latestId, options);
+}
+
+/**
+ * Auto-rollback on failure during in-progress session
+ * @param {string} cwd
+ * @param {Session} session
+ * @param {Object} [options]
+ * @returns {{restored: number, skipped: number}}
+ */
+function autoRollback(cwd, session, options = {}) {
+  const { log = console.log } = options;
+  log('Auto-rollback initiated...');
+  const result = restoreSession(cwd, session.id, options);
+  session.rollback();
+  log(`Rolled back ${result.restored} files`);
+  return result;
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Object|null}
+ */
+function checkIncompleteSession(cwd) {
+  const incomplete = Session.findIncomplete(cwd);
+  return incomplete.length > 0 ? incomplete[0] : null;
+}
+
+/**
+ * Returns preview of restore operation
+ * @param {string} cwd
+ * @param {string} sessionId
+ * @returns {Object|null}
+ */
+function formatRestorePreview(cwd, sessionId) {
+  const session = Session.load(cwd, sessionId);
+  if (!session) {
+    return null;
+  }
+  const files = session.getBackedUpFiles();
+  const sessionDir = getSessionDir(cwd, sessionId);
+  const { command, timestamp } = session.manifest;
+  return {
+    sessionId,
+    command,
+    timestamp,
+    status: session.status,
+    fileCount: files.length,
+    files: files.map(f => ({ path: f.original, exists: fs.existsSync(f.backup) })),
+    sessionDir,
+  };
+}
+
+function buildRecoveryActions(id) {
+  return [
+    { command: `i18nkit --restore ${id}`, description: 'Rollback to pre-modification state' },
+    { command: 'i18nkit --force', description: 'Continue without rollback (risky)' },
+  ];
+}
+
+function getInProgressRecovery(id) {
+  return {
+    severity: 'warning',
+    message: `Incomplete session found: ${id}`,
+    suggestion: `Files may have been partially modified. Run 'i18nkit --restore ${id}' to rollback.`,
+    actions: buildRecoveryActions(id),
+  };
+}
+
+function getBackingUpRecovery() {
+  return {
+    severity: 'info',
+    message: 'Interrupted backup session',
+    suggestion: 'Backup was incomplete. No files were modified. Safe to continue.',
+    actions: [{ command: 'i18nkit [command]', description: 'Continue normally' }],
+  };
+}
+
+/**
+ * Returns recovery instructions for incomplete session
+ * @param {Object|null} incomplete
+ * @returns {Object|null}
+ */
+function getRecoveryInstructions(incomplete) {
+  if (!incomplete) {
+    return null;
+  }
+  const { status, id } = incomplete;
+  if (status === SessionStatus.IN_PROGRESS) {
+    return getInProgressRecovery(id);
+  }
+  if (status === SessionStatus.BACKING_UP) {
+    return getBackingUpRecovery();
+  }
+  return null;
+}
+
+module.exports = {
+  restoreSession,
+  restoreLatest,
+  autoRollback,
+  checkIncompleteSession,
+  formatRestorePreview,
+  getRecoveryInstructions,
+};

package/bin/core/backup/session.js

@@ -0,0 +1,258 @@
+'use strict';
+
+/**
+ * @fileoverview Backup session lifecycle management.
+ * @module backup/session
+ */
+
+const path = require('path');
+const crypto = require('crypto');
+const {
+  SessionStatus,
+  VALID_TRANSITIONS,
+  getSessionDir,
+  getBackupsDir,
+  getLatestFile,
+} = require('./constants');
+const { ensureDirSync, copyFilePreservingStructureSync, listDirsSync } = require('./file-ops');
+const {
+  createManifest,
+  addFileToManifest,
+  updateManifestStatus,
+  writeManifestSync,
+  readManifestSync,
+} = require('./manifest');
+const fs = require('../fs-adapter');
+
+/**
+ * Generates unique session ID: YYYY-MM-DD_HH-MM-SS_command_rand
+ * @param {string} command
+ * @returns {string}
+ */
+function generateSessionId(command) {
+  const now = new Date();
+  const date = now.toISOString().slice(0, 10);
+  const time = now.toTimeString().slice(0, 8).replace(/:/g, '-');
+  const cmd = command.replace(/[^a-zA-Z0-9]/g, '-').slice(0, 20);
+  const rand = crypto.randomBytes(2).toString('hex');
+  return `${date}_${time}_${cmd}_${rand}`;
+}
+
+/**
+ * @param {string} sessionId
+ * @returns {{id: string, timestamp: Date, date: string, time: string}|null}
+ */
+function parseSessionId(sessionId) {
+  const parts = sessionId.split('_');
+  if (parts.length < 4) {
+    return null;
+  }
+  const [date, time] = parts;
+  const timestamp = new Date(`${date}T${time.replace(/-/g, ':')}`);
+  return { id: sessionId, timestamp, date, time };
+}
+
+function getManifestValue(manifest, key, defaultValue) {
+  return manifest?.[key] || defaultValue;
+}
+
+function extractSessionInfo(manifest, dir) {
+  return {
+    id: dir,
+    status: getManifestValue(manifest, 'status', 'unknown'),
+    fileCount: manifest?.files?.length || 0,
+    command: getManifestValue(manifest, 'command', 'unknown'),
+  };
+}
+
+function parseSessionForList(cwd, dir) {
+  const parsed = parseSessionId(dir);
+  if (!parsed) {
+    return null;
+  }
+  const manifest = readManifestSync(cwd, dir);
+  return {
+    ...extractSessionInfo(manifest, dir),
+    timestamp: parsed.timestamp,
+  };
+}
+
+/**
+ * Backup session with state machine lifecycle
+ */
+class Session {
+  /**
+   * @param {string} cwd
+   * @param {string} command
+   * @param {string} [sessionId]
+   */
+  constructor(cwd, command, sessionId = null) {
+    this.cwd = cwd;
+    this.command = command;
+    this.id = sessionId || generateSessionId(command);
+    this.sessionDir = getSessionDir(cwd, this.id);
+    this.manifest = createManifest(this.id, command, cwd);
+    this.files = [];
+  }
+
+  get status() {
+    return this.manifest.status;
+  }
+
+  validateTransition(newStatus) {
+    const allowed = VALID_TRANSITIONS[this.status] || [];
+    if (!allowed.includes(newStatus)) {
+      throw new Error(`Invalid transition: ${this.status} -> ${newStatus}`);
+    }
+  }
+
+  setStatus(status, stats = null, error = null) {
+    this.validateTransition(status);
+    updateManifestStatus(this.manifest, { status, stats, error });
+    this.save();
+  }
+
+  save() {
+    ensureDirSync(this.sessionDir);
+    writeManifestSync(this.cwd, this.id, this.manifest);
+  }
+
+  start() {
+    this.setStatus(SessionStatus.BACKING_UP);
+    return this;
+  }
+
+  backupFile(filePath) {
+    if (this.status !== SessionStatus.BACKING_UP) {
+      throw new Error(`Cannot backup file in status: ${this.status}`);
+    }
+    const fileInfo = copyFilePreservingStructureSync(filePath, this.sessionDir, this.cwd);
+    addFileToManifest(this.manifest, fileInfo);
+    this.files.push(fileInfo);
+    this.save();
+    return fileInfo;
+  }
+
+  markReady() {
+    this.setStatus(SessionStatus.READY);
+    return this;
+  }
+
+  beginModifications() {
+    this.setStatus(SessionStatus.IN_PROGRESS);
+    return this;
+  }
+
+  saveReport(reportPath) {
+    if (!fs.existsSync(reportPath)) {
+      return null;
+    }
+    const reportDest = path.join(this.sessionDir, 'report.json');
+    fs.copyFileSync(reportPath, reportDest);
+    this.manifest.reportFile = 'report.json';
+    this.save();
+    return reportDest;
+  }
+
+  complete(stats = {}) {
+    this.setStatus(SessionStatus.COMPLETED, stats);
+    this.updateLatest();
+    return this;
+  }
+
+  rollback() {
+    this.setStatus(SessionStatus.ROLLED_BACK);
+    return this;
+  }
+
+  fail(error) {
+    updateManifestStatus(this.manifest, { status: SessionStatus.FAILED, error });
+    this.save();
+    return this;
+  }
+
+  updateLatest() {
+    const latestFile = getLatestFile(this.cwd);
+    try {
+      fs.writeFileSync(latestFile, this.id, 'utf-8');
+    } catch {
+      // Non-critical: latest file update failure is acceptable
+    }
+  }
+
+  getBackedUpFiles() {
+    return this.manifest.files.map(f => ({
+      original: path.join(this.cwd, f.original),
+      backup: path.join(this.sessionDir, f.backup),
+      size: f.size,
+    }));
+  }
+
+  /**
+   * @param {string} cwd
+   * @param {string} sessionId
+   * @returns {Session|null}
+   */
+  static load(cwd, sessionId) {
+    const manifest = readManifestSync(cwd, sessionId);
+    if (!manifest) {
+      return null;
+    }
+    const session = new Session(cwd, manifest.command, sessionId);
+    session.manifest = manifest;
+    session.files = manifest.files || [];
+    return session;
+  }
+
+  /**
+   * @param {string} cwd
+   * @returns {string|null}
+   */
+  static getLatestId(cwd) {
+    const latestFile = getLatestFile(cwd);
+    try {
+      return fs.readFileSync(latestFile, 'utf-8').trim();
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * @param {string} cwd
+   * @returns {Session|null}
+   */
+  static loadLatest(cwd) {
+    const latestId = Session.getLatestId(cwd);
+    return latestId ? Session.load(cwd, latestId) : null;
+  }
+
+  /**
+   * @param {string} cwd
+   * @returns {Object[]}
+   */
+  static listAll(cwd) {
+    const backupsDir = getBackupsDir(cwd);
+    const dirs = listDirsSync(backupsDir);
+    return dirs
+      .map(dir => parseSessionForList(cwd, dir))
+      .filter(Boolean)
+      .sort((a, b) => b.timestamp - a.timestamp);
+  }
+
+  /**
+   * @param {string} cwd
+   * @returns {Object[]}
+   */
+  static findIncomplete(cwd) {
+    const sessions = Session.listAll(cwd);
+    return sessions.filter(
+      s => s.status === SessionStatus.BACKING_UP || s.status === SessionStatus.IN_PROGRESS,
+    );
+  }
+}
+
+module.exports = {
+  Session,
+  generateSessionId,
+  parseSessionId,
+};

package/bin/core/backup.js

@@ -1,74 +1,124 @@
 'use strict';
 
 /**
- * @fileoverview File backup and restore for safe source modifications.
- * Creates timestamped backups before applying changes.
+ * @fileoverview Backward-compatible backup API wrapping new session-based system.
  * @module backup
+ * @deprecated Use backup/index.js for new code
  */
 
-const fs = require('./fs-adapter');
-const path = require('path');
+const backup = require('./backup/index');
 
-const backupFiles = new Map();
+let currentSession = null;
+const legacyBackupFiles = new Map();
 
-function buildBackupPath(filePath, backupDir) {
-  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-  const relativePath = path.relative(process.cwd(), filePath);
-  return path.join(backupDir, `${timestamp}_${relativePath.replace(/[/\\]/g, '_')}`);
+function initSessionIfNeeded(cwd) {
+  if (!currentSession) {
+    currentSession = backup.createBackupSession(cwd, 'legacy-apply');
+  }
+  return currentSession;
+}
+
+function tryBackupFile(session, filePath) {
+  const fileInfo = session.backupFile(filePath);
+  const backupPath = require('path').join(session.sessionDir, fileInfo.backup);
+  legacyBackupFiles.set(filePath, backupPath);
+  return backupPath;
 }
 
-function writeBackupFile(filePath, backupPath) {
+function shouldSkipLegacyBackup(enabled, dryRun) {
+  return !enabled || dryRun;
+}
+
+function performLegacyBackup(filePath) {
+  const cwd = process.cwd();
+  const session = initSessionIfNeeded(cwd);
   try {
-    const content = fs.readFileSync(filePath, 'utf-8');
-    fs.writeFileSync(backupPath, content, 'utf-8');
-    backupFiles.set(filePath, backupPath);
-    return backupPath;
+    return tryBackupFile(session, filePath);
   } catch (err) {
     console.warn(`Warning: Cannot backup ${filePath}: ${err.message}`);
     return null;
   }
 }
 
-function shouldSkipBackup(enabled, dryRun) {
-  return !enabled || dryRun;
-}
-
 /**
- * Creates a timestamped backup of a file
- * @param {string} filePath
- * @param {string} backupDir
- * @param {Object} [options]
+ * Creates a backup of a file (legacy API)
+ * @param {string} filePath - File to backup
+ * @param {string} _backupDir - Backup directory (ignored, uses .i18nkit/backups)
+ * @param {Object} [options] - Options
  * @returns {string|null} Backup path or null if skipped
  */
-function createBackup(filePath, backupDir, options = {}) {
+function createBackup(filePath, _backupDir, options = {}) {
   const { enabled = true, dryRun = false } = options;
-  if (shouldSkipBackup(enabled, dryRun)) {
-    return null;
-  }
-  fs.mkdirSync(backupDir, { recursive: true });
-  return writeBackupFile(filePath, buildBackupPath(filePath, backupDir));
+  return shouldSkipLegacyBackup(enabled, dryRun) ? null : performLegacyBackup(filePath);
 }
 
 /**
- * Restores all backed-up files to their original locations
+ * Restores all backed-up files (legacy API)
  * @returns {number} Count of restored files
  */
 function restoreBackups() {
-  let restored = 0;
-  for (const [original, backup] of backupFiles) {
-    try {
-      const content = fs.readFileSync(backup, 'utf-8');
-      fs.writeFileSync(original, content, 'utf-8');
-      restored++;
-    } catch {
-      console.error(`Cannot restore ${original} from ${backup}`);
-    }
+  if (!currentSession) {
+    return 0;
   }
-  return restored;
+  const cwd = process.cwd();
+  const result = backup.restoreSession(cwd, currentSession.id, { verbose: false });
+  return result.restored;
 }
 
+/**
+ * Gets the map of backed-up files (legacy API)
+ * @returns {Map<string, string>}
+ */
 function getBackupFiles() {
-  return backupFiles;
+  return legacyBackupFiles;
 }
 
-module.exports = { createBackup, restoreBackups, getBackupFiles };
+/**
+ * Marks session as ready for modifications (new API bridge)
+ */
+function markReady() {
+  if (currentSession && currentSession.status === 'backing-up') {
+    currentSession.markReady();
+  }
+}
+
+/**
+ * Begins modification phase (new API bridge)
+ */
+function beginModifications() {
+  if (currentSession && currentSession.status === 'ready') {
+    currentSession.beginModifications();
+  }
+}
+
+/**
+ * Completes the backup session (new API bridge)
+ * @param {Object} [stats] - Operation stats
+ */
+function completeSession(stats = {}) {
+  if (currentSession) {
+    currentSession.complete(stats);
+    currentSession = null;
+    legacyBackupFiles.clear();
+  }
+}
+
+/**
+ * Resets session state (for testing)
+ */
+function resetSession() {
+  currentSession = null;
+  legacyBackupFiles.clear();
+}
+
+module.exports = {
+  createBackup,
+  restoreBackups,
+  getBackupFiles,
+  markReady,
+  beginModifications,
+  completeSession,
+  resetSession,
+
+  ...backup,
+};

package/bin/core/command-interface.js

@@ -11,6 +11,7 @@ const COMMAND_CATEGORIES = Object.freeze([
   { id: 'validation', label: 'VALIDATION' },
   { id: 'translation', label: 'TRANSLATION' },
   { id: 'development', label: 'DEVELOPMENT' },
+  { id: 'maintenance', label: 'MAINTENANCE' },
 ]);
 
 const getDescription = cmd => cmd.description || cmd.meta?.description || 'No description';