@abdess76/i18nkit 1.0.3 → 1.0.5

package/bin/core/backup/gitignore.js

@@ -0,0 +1,173 @@
+'use strict';
+
+/**
+ * @fileoverview Gitignore management for backup directories.
+ * @module backup/gitignore
+ */
+
+const path = require('path');
+const fs = require('../fs-adapter');
+const { BACKUP_ROOT, GITIGNORE_FILE } = require('./constants');
+const { atomicWriteSync, ensureDirSync } = require('./file-ops');
+
+const I18NKIT_GITIGNORE_CONTENT = `# i18nkit generated - do not edit
+backups/
+report.json
+reports/
+cache/
+*.log
+*.tmp
+`;
+
+const PROJECT_GITIGNORE_ENTRY = '.i18nkit/';
+const GITIGNORE_MARKER = '# i18nkit';
+const REQUIRED_ENTRIES = ['backups/', 'report.json', 'reports/'];
+
+function getMissingEntries(content) {
+  return REQUIRED_ENTRIES.filter(entry => !content.includes(entry));
+}
+
+function createGitignore(gitignorePath) {
+  atomicWriteSync(gitignorePath, I18NKIT_GITIGNORE_CONTENT);
+  return { created: true, updated: false, path: gitignorePath };
+}
+
+function updateGitignoreContent(gitignorePath, content, missing) {
+  const additions = missing.join('\n');
+  const separator = content.endsWith('\n') ? '' : '\n';
+  const updated = `${content}${separator}${additions}\n`;
+  atomicWriteSync(gitignorePath, updated);
+  return { created: false, updated: true, added: missing, path: gitignorePath };
+}
+
+/**
+ * Creates or updates .i18nkit/.gitignore
+ * @param {string} cwd
+ * @returns {{created: boolean, updated: boolean, path: string}}
+ */
+function ensureI18nkitGitignore(cwd) {
+  const i18nkitDir = path.join(cwd, BACKUP_ROOT);
+  const gitignorePath = path.join(i18nkitDir, GITIGNORE_FILE);
+  ensureDirSync(i18nkitDir);
+  if (!fs.existsSync(gitignorePath)) {
+    return createGitignore(gitignorePath);
+  }
+  const content = fs.readFileSync(gitignorePath, 'utf-8');
+  const missing = getMissingEntries(content);
+  if (missing.length > 0) {
+    return updateGitignoreContent(gitignorePath, content, missing);
+  }
+  return { created: false, updated: false, path: gitignorePath };
+}
+
+/**
+ * @param {string} cwd
+ * @returns {{exists: boolean, hasEntry: boolean, path: string}}
+ */
+function checkProjectGitignore(cwd) {
+  const gitignorePath = path.join(cwd, '.gitignore');
+  if (!fs.existsSync(gitignorePath)) {
+    return { exists: false, hasEntry: false, path: gitignorePath };
+  }
+  const content = fs.readFileSync(gitignorePath, 'utf-8');
+  const hasEntry = content.includes(PROJECT_GITIGNORE_ENTRY) || content.includes(BACKUP_ROOT);
+  return { exists: true, hasEntry, path: gitignorePath };
+}
+
+/**
+ * Returns suggestion if .i18nkit/ not in project .gitignore
+ * @param {string} cwd
+ * @returns {{message: string, entry: string, path: string}|null}
+ */
+function suggestGitignoreUpdate(cwd) {
+  const check = checkProjectGitignore(cwd);
+  if (check.hasEntry) {
+    return null;
+  }
+  return {
+    message: `Add "${PROJECT_GITIGNORE_ENTRY}" to your .gitignore`,
+    entry: PROJECT_GITIGNORE_ENTRY,
+    path: check.path,
+  };
+}
+
+function buildGitignoreEntry() {
+  return `\n${GITIGNORE_MARKER}\n${PROJECT_GITIGNORE_ENTRY}\n`;
+}
+
+function appendToExistingGitignore(gitignorePath, content) {
+  const newEntry = buildGitignoreEntry();
+  const separator = content.endsWith('\n') ? '' : '\n';
+  atomicWriteSync(gitignorePath, `${content}${separator}${newEntry}`);
+}
+
+function createNewGitignore(gitignorePath) {
+  const newEntry = buildGitignoreEntry();
+  atomicWriteSync(gitignorePath, `${newEntry.trim()}\n`);
+}
+
+/**
+ * Adds .i18nkit/ to project .gitignore
+ * @param {string} cwd
+ * @returns {Object} Result with added, reason, path properties
+ */
+function addToProjectGitignore(cwd) {
+  const check = checkProjectGitignore(cwd);
+  if (check.hasEntry) {
+    return { added: false, reason: 'Already present' };
+  }
+  if (check.exists) {
+    const content = fs.readFileSync(check.path, 'utf-8');
+    appendToExistingGitignore(check.path, content);
+  } else {
+    createNewGitignore(check.path);
+  }
+  return { added: true, path: check.path };
+}
+
+function handleAutoGitignore(cwd, verbose, log) {
+  const result = addToProjectGitignore(cwd);
+  if (result.added && verbose) {
+    log(`Added ${PROJECT_GITIGNORE_ENTRY} to ${result.path}`);
+  }
+}
+
+function logCreation(result, verbose, log) {
+  if (result.created && verbose) {
+    log(`Created ${result.path}`);
+  }
+}
+
+function processSuggestion(ctx) {
+  const { cwd, suggestion, autoAddGitignore, verbose, log } = ctx;
+  if (suggestion && autoAddGitignore) {
+    handleAutoGitignore(cwd, verbose, log);
+    return null;
+  }
+  return suggestion;
+}
+
+/**
+ * Initializes .i18nkit directory structure and gitignore
+ * @param {string} cwd
+ * @param {Object} [options]
+ * @returns {{initialized: boolean, suggestion: Object|null}}
+ */
+function initializeBackupStructure(cwd, options = {}) {
+  const { autoAddGitignore = false, log = console.log, verbose = false } = options;
+  const i18nkitResult = ensureI18nkitGitignore(cwd);
+  logCreation(i18nkitResult, verbose, log);
+  const suggestion = suggestGitignoreUpdate(cwd);
+  const finalSuggestion = processSuggestion({ cwd, suggestion, autoAddGitignore, verbose, log });
+  return { initialized: true, suggestion: finalSuggestion };
+}
+
+module.exports = {
+  ensureI18nkitGitignore,
+  checkProjectGitignore,
+  suggestGitignoreUpdate,
+  addToProjectGitignore,
+  initializeBackupStructure,
+  I18NKIT_GITIGNORE_CONTENT,
+  PROJECT_GITIGNORE_ENTRY,
+};

package/bin/core/backup/index.js

@@ -0,0 +1,189 @@
+'use strict';
+
+/**
+ * @fileoverview Backup system public API.
+ * @module backup
+ */
+
+const { Session, generateSessionId, parseSessionId } = require('./session');
+const { validateManifest, formatManifestForDisplay } = require('./manifest');
+const {
+  restoreSession,
+  restoreLatest,
+  autoRollback,
+  checkIncompleteSession,
+  formatRestorePreview,
+  getRecoveryInstructions,
+} = require('./restore');
+const { cleanupOldSessions, getCleanupPreview, autoCleanupIfEnabled } = require('./cleanup');
+const {
+  ensureI18nkitGitignore,
+  suggestGitignoreUpdate,
+  addToProjectGitignore,
+  initializeBackupStructure,
+} = require('./gitignore');
+const {
+  SessionStatus,
+  DEFAULT_CONFIG,
+  BACKUP_ROOT,
+  getBackupRoot,
+  getBackupsDir,
+  getSessionDir,
+} = require('./constants');
+
+/**
+ * Creates and starts a new backup session
+ * @param {string} cwd
+ * @param {string} command
+ * @returns {Session}
+ */
+function createBackupSession(cwd, command) {
+  const session = new Session(cwd, command);
+  initializeBackupStructure(cwd, { verbose: false });
+  return session.start();
+}
+
+function logIncompleteWarning(instructions, log) {
+  log(`\nWarning: ${instructions.message}`);
+  log(`  ${instructions.suggestion}\n`);
+}
+
+function handleIncompleteSession(cwd, log) {
+  const incomplete = checkIncompleteSession(cwd);
+  if (!incomplete) {
+    return;
+  }
+  const instructions = getRecoveryInstructions(incomplete);
+  if (instructions?.severity === 'warning') {
+    logIncompleteWarning(instructions, log);
+  }
+}
+
+function executeWithSession(session, operation) {
+  const result = operation({
+    backupFile: filePath => session.backupFile(filePath),
+    markReady: () => session.markReady(),
+    beginModifications: () => session.beginModifications(),
+    saveReport: reportPath => session.saveReport(reportPath),
+  });
+  session.complete({ filesModified: session.files.length });
+  return result;
+}
+
+function logBackupSuccess(session, verbose, log) {
+  if (verbose) {
+    log(`Backup session: ${session.id}`);
+    log(`Files backed up: ${session.files.length}`);
+  }
+}
+
+function handleSuggestion(cwd, log) {
+  const suggestion = suggestGitignoreUpdate(cwd);
+  if (suggestion) {
+    log(`\nTip: ${suggestion.message}`);
+  }
+}
+
+function handleSessionError(session, error) {
+  if (session.status === SessionStatus.IN_PROGRESS) {
+    autoRollback(session.cwd, session, { log: console.log, verbose: false });
+  } else {
+    session.fail(error);
+  }
+}
+
+function shouldSkipBackup(backup, dryRun) {
+  return !backup || dryRun;
+}
+
+function handleBackupSuccess(ctx) {
+  const { session, cwd, options } = ctx;
+  const { log = console.log, verbose = false } = options;
+  logBackupSuccess(session, verbose, log);
+  handleSuggestion(cwd, log);
+  autoCleanupIfEnabled(cwd, { ...DEFAULT_CONFIG, ...options });
+}
+
+function runWithBackup(ctx) {
+  const { cwd, command, operation, options } = ctx;
+  handleIncompleteSession(cwd, options.log || console.log);
+  const session = createBackupSession(cwd, command);
+  try {
+    const result = executeWithSession(session, operation);
+    handleBackupSuccess({ session, cwd, options });
+    return result;
+  } catch (error) {
+    handleSessionError(session, error);
+    throw error;
+  }
+}
+
+/**
+ * Wraps operation with backup session lifecycle
+ * @param {Object} ctx - Context with cwd, command, operation, options
+ * @returns {*} Operation result
+ */
+function withBackup(ctx) {
+  const { cwd, command, operation, options = {} } = ctx;
+  const { backup = true, dryRun = false } = options;
+  if (shouldSkipBackup(backup, dryRun)) {
+    return operation();
+  }
+  return runWithBackup({ cwd, command, operation, options });
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Object[]}
+ */
+function listBackupSessions(cwd) {
+  return Session.listAll(cwd);
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} sessionId
+ * @returns {Session|null}
+ */
+function getBackupSession(cwd, sessionId) {
+  return Session.load(cwd, sessionId);
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Session|null}
+ */
+function getLatestBackupSession(cwd) {
+  return Session.loadLatest(cwd);
+}
+
+module.exports = {
+  Session,
+  SessionStatus,
+  DEFAULT_CONFIG,
+  BACKUP_ROOT,
+  createBackupSession,
+  withBackup,
+  listBackupSessions,
+  getBackupSession,
+  getLatestBackupSession,
+  restoreSession,
+  restoreLatest,
+  autoRollback,
+  checkIncompleteSession,
+  getRecoveryInstructions,
+  formatRestorePreview,
+  cleanupOldSessions,
+  getCleanupPreview,
+  initializeBackupStructure,
+  ensureI18nkitGitignore,
+  suggestGitignoreUpdate,
+  addToProjectGitignore,
+  generateSessionId,
+  parseSessionId,
+  validateManifest,
+  formatManifestForDisplay,
+  getBackupRoot,
+  getBackupsDir,
+  getSessionDir,
+};

package/bin/core/backup/manifest.js

@@ -0,0 +1,185 @@
+'use strict';
+
+/**
+ * @fileoverview Session manifest creation and persistence.
+ * @module backup/manifest
+ */
+
+const fs = require('../fs-adapter');
+const path = require('path');
+const { atomicWrite, atomicWriteSync } = require('./file-ops');
+const { MANIFEST_FILE, getSessionDir } = require('./constants');
+
+const MANIFEST_VERSION = '1.0';
+
+/**
+ * Creates new session manifest
+ * @param {string} sessionId
+ * @param {string} command
+ * @param {string} cwd
+ * @returns {Object}
+ */
+function createManifest(sessionId, command, cwd) {
+  return {
+    version: MANIFEST_VERSION,
+    id: sessionId,
+    timestamp: new Date().toISOString(),
+    command,
+    cwd,
+    status: 'pending',
+    files: [],
+    reportFile: null,
+    stats: { filesModified: 0, filesBackedUp: 0 },
+    error: null,
+  };
+}
+
+/**
+ * @param {Object} manifest
+ * @param {{original: string, backup: string, size: number}} fileInfo
+ */
+function addFileToManifest(manifest, fileInfo) {
+  manifest.files.push({
+    original: fileInfo.original,
+    backup: fileInfo.backup,
+    size: fileInfo.size,
+    backedUpAt: new Date().toISOString(),
+  });
+  manifest.stats.filesBackedUp = manifest.files.length;
+}
+
+/**
+ * @param {Object} manifest
+ * @param {Object} ctx - Context with status, stats, error properties
+ */
+function updateManifestStatus(manifest, ctx) {
+  const { status, stats = null, error = null } = ctx;
+  manifest.status = status;
+  manifest.updatedAt = new Date().toISOString();
+  if (stats) {
+    manifest.stats = { ...manifest.stats, ...stats };
+  }
+  if (error) {
+    manifest.error = {
+      message: error.message,
+      stack: error.stack,
+      occurredAt: new Date().toISOString(),
+    };
+  }
+}
+
+function getManifestPath(cwd, sessionId) {
+  return path.join(getSessionDir(cwd, sessionId), MANIFEST_FILE);
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} sessionId
+ * @param {Object} manifest
+ * @returns {Promise<void>}
+ */
+async function writeManifest(cwd, sessionId, manifest) {
+  const manifestPath = getManifestPath(cwd, sessionId);
+  const content = JSON.stringify(manifest, null, 2);
+  await atomicWrite(manifestPath, content);
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} sessionId
+ * @param {Object} manifest
+ */
+function writeManifestSync(cwd, sessionId, manifest) {
+  const manifestPath = getManifestPath(cwd, sessionId);
+  const content = JSON.stringify(manifest, null, 2);
+  atomicWriteSync(manifestPath, content);
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} sessionId
+ * @returns {Promise<Object|null>}
+ */
+async function readManifest(cwd, sessionId) {
+  const manifestPath = getManifestPath(cwd, sessionId);
+  try {
+    const content = await fs.readFile(manifestPath, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} sessionId
+ * @returns {Object|null}
+ */
+function readManifestSync(cwd, sessionId) {
+  const manifestPath = getManifestPath(cwd, sessionId);
+  try {
+    const content = fs.readFileSync(manifestPath, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+function hasRequiredField(manifest, field) {
+  return Boolean(manifest[field]);
+}
+
+/**
+ * @param {Object} manifest
+ * @returns {Object} Result with valid and error properties
+ */
+function validateManifest(manifest) {
+  if (!manifest) {
+    return { valid: false, error: 'Manifest is null' };
+  }
+  const requiredFields = [
+    { field: 'version', error: 'Missing version' },
+    { field: 'id', error: 'Missing session id' },
+    { field: 'timestamp', error: 'Missing timestamp' },
+  ];
+  for (const { field, error } of requiredFields) {
+    if (!hasRequiredField(manifest, field)) {
+      return { valid: false, error };
+    }
+  }
+  if (!Array.isArray(manifest.files)) {
+    return { valid: false, error: 'Invalid files array' };
+  }
+  return { valid: true };
+}
+
+function formatDate(timestamp) {
+  return timestamp ? new Date(timestamp).toLocaleString() : 'unknown';
+}
+
+/**
+ * @param {Object} manifest
+ * @returns {Object}
+ */
+function formatManifestForDisplay(manifest) {
+  return {
+    id: manifest.id,
+    date: formatDate(manifest.timestamp),
+    status: manifest.status || 'unknown',
+    fileCount: manifest.files?.length || 0,
+    command: manifest.command || 'unknown',
+    hasReport: Boolean(manifest.reportFile),
+  };
+}
+
+module.exports = {
+  createManifest,
+  addFileToManifest,
+  updateManifestStatus,
+  writeManifest,
+  writeManifestSync,
+  readManifest,
+  readManifestSync,
+  validateManifest,
+  formatManifestForDisplay,
+};