@abdess76/i18nkit 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -6,6 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.4] - 05-01-2026
+
+### Added
+
+- Backup system with session-linked reports
+- Automatic report archival in backup sessions
+- Restore/rollback capabilities from backup sessions
+- Auto-cleanup of old backup sessions
+- Gitignore auto-management for `.i18nkit` directory
+- Manifest schema with `reportFile` field for audit trail
+
+### Changed
+
+- Backup directory renamed from `.i18n` to `.i18nkit`
+- Report files now stored alongside backup sessions
+- Improved session status tracking (pending, ready, in_progress, completed,
+  failed)
+
 ## [1.0.3] - 05-01-2026
 
 ### Changed

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Abdessamad DERRAZ
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Abdessamad DERRAZ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -50,7 +50,7 @@ npm install --save-dev @abdess76/i18nkit
     "i18n:apply": "i18nkit --auto-apply --init-langs en,fr",
     "i18n:check": "i18nkit --check-sync --strict",
     "i18n:orphans": "i18nkit --find-orphans --strict",
-    "i18n:translate": "i18nkit --translate fr:en",
+    "i18n:translate": "i18nkit --translate en:fr",
     "i18n:watch": "i18nkit --watch",
     "i18n:ci": "npm run i18n:check && npm run i18n:orphans"
   }
@@ -88,7 +88,7 @@ npm run i18n:ci
 <input [placeholder]="'home.forms.enter_your_name' | transloco" />
 ```
 
-**Generated `fr.json`:**
+**Generated `en.json`:**
 
 ```json
 {
@@ -102,13 +102,26 @@ npm run i18n:ci
 
 ## Commands
 
+### Core Commands
+
+| Command        | Description                              |
+| -------------- | ---------------------------------------- |
+| `extract`      | Extract i18n strings from source files   |
+| `check-sync`   | Compare language files for missing keys  |
+| `find-orphans` | Find translation keys not used in source |
+| `translate`    | Translate a language file via API        |
+| `watch`        | Watch for file changes and re-run        |
+| `backup`       | Manage backup sessions and restore files |
+
+### NPM Scripts Examples
+
 | Script                   | Command                     | Description                  |
 | ------------------------ | --------------------------- | ---------------------------- |
 | `npm run i18n`           | `--lang fr --merge`         | Extract, merge with existing |
 | `npm run i18n:apply`     | `--auto-apply --init-langs` | Extract + replace + create   |
 | `npm run i18n:check`     | `--check-sync --strict`     | Validate files are in sync   |
 | `npm run i18n:orphans`   | `--find-orphans --strict`   | Find unused keys             |
-| `npm run i18n:translate` | `--translate fr:en`         | Translate via API            |
+| `npm run i18n:translate` | `--translate en:fr`         | Translate via API            |
 | `npm run i18n:watch`     | `--watch`                   | Re-run on file changes       |
 
 ## Configuration
@@ -188,6 +201,105 @@ jobs:
       - run: npm run i18n:ci
 ```
 
+## Backup & Restore
+
+Source files are backed up before modification. Full session management with
+restore, cleanup, and audit capabilities.
+
+### Automatic Backup
+
+```bash
+# Backup enabled by default with --auto-apply
+npm run i18n:apply
+
+# Disable backup if needed
+npx i18nkit --auto-apply --no-backup
+
+# Initialize backup structure explicitly
+npx i18nkit --init-backups --auto-gitignore
+```
+
+### Session Structure
+
+```text
+.i18nkit/
+├── .gitignore              # Auto-managed (excludes backups/, report.json)
+├── report.json             # Current extraction report
+└── backups/
+    └── 2026-01-05_15-39-28_apply_ae9c/
+        ├── manifest.json   # Session metadata with status tracking
+        ├── report.json     # Archived extraction report
+        └── src/            # Original source files
+```
+
+### Session Management
+
+```bash
+# List all backup sessions
+npx i18nkit --list-backups
+
+# Show detailed info for a session
+npx i18nkit --backup-info 2026-01-05_15-39-28_apply_ae9c
+```
+
+### Restore from Backup
+
+```bash
+# Restore specific session
+npx i18nkit --restore 2026-01-05_15-39-28_apply_ae9c
+
+# Restore latest session
+npx i18nkit --restore-latest
+
+# Preview restore without applying
+npx i18nkit --restore-latest --dry-run
+```
+
+### Manual Cleanup
+
+```bash
+# Clean old sessions (interactive)
+npx i18nkit --cleanup-backups
+
+# Keep only last 5 sessions
+npx i18nkit --cleanup-backups --keep 5
+
+# Remove sessions older than 7 days
+npx i18nkit --cleanup-backups --max-age 7
+
+# Combine options
+npx i18nkit --cleanup-backups --keep 3 --max-age 14
+```
+
+### Auto-Cleanup Configuration
+
+Old sessions are automatically cleaned up based on configuration.
+
+```javascript
+// i18nkit.config.js
+module.exports = {
+  backup: {
+    enabled: true,
+    maxSessions: 10, // Keep max 10 sessions
+    retentionDays: 30, // Delete sessions older than 30 days
+    autoCleanup: true, // Auto-cleanup on each run
+  },
+};
+```
+
+### Session Status
+
+Sessions track their lifecycle status:
+
+| Status        | Description                      |
+| ------------- | -------------------------------- |
+| `pending`     | Session created, not started     |
+| `backing_up`  | Backup in progress               |
+| `in_progress` | Apply operation running          |
+| `completed`   | Successfully finished            |
+| `failed`      | Error occurred (check manifest)  |
+| `restored`    | Files restored from this session |
+
 ## Key Mapping
 
 Override auto-generated keys with `.i18n-keys.json`:
@@ -251,23 +363,70 @@ implementations.
 
 ## Options
 
+### Global Options
+
 ```text
+--config <path>       Path to config file (default: i18nkit.config.js)
 --src <path>          Source directory (default: src/app)
---i18n-dir <path>     i18n directory (default: src/assets/i18n)
---lang <code>         Language code
---format <type>       nested | flat (default: nested)
+--locales <path>      Locales directory (default: src/assets/i18n)
+--default-lang <code> Default language (default: fr)
+--dry-run             Preview changes without writing
+--verbose             Detailed output
+--help, -h            Show help
+--version, -v         Show version
+```
+
+### Extraction Options
+
+```text
+--lang <code>         Language code for output file
+--format <type>       Output format: nested | flat (default: nested)
 --merge               Merge with existing translations
---auto-apply          Extract and apply pipes
+--auto-apply          Extract AND apply pipes in one command
 --init-langs <codes>  Create language files (e.g., en,fr,es)
---check-sync          Compare language files
---find-orphans        Find unused keys
---translate <src:tgt> Translate via API (e.g., fr:en)
---deepl               Use DeepL API
---watch               Watch mode
---dry-run             Preview only
---strict              Exit 1 on issues
+--include-translated  Include already translated strings
+--extract-ts-objects  Extract from TypeScript object literals
+--skip-translated     Skip already translated strings (default: true)
+```
+
+### Validation Options
+
+```text
+--check-sync          Compare language files for missing keys
+--find-orphans        Find unused translation keys
+--strict              Exit with error code 1 on issues
 --ci                  CI mode (strict + json output)
---verbose             Detailed output
+```
+
+### Translation Options
+
+```text
+--translate <src:tgt> Translate via API (e.g., fr:en)
+--deepl               Use DeepL API (requires DEEPL_API_KEY)
+--mymemory            Use MyMemory API (default)
+--email <email>       Email for MyMemory rate limits
+```
+
+### Backup Options
+
+```text
+--backup              Enable backup before modifications (default)
+--no-backup           Disable backup
+--list-backups        List all backup sessions
+--backup-info <id>    Show backup session details
+--restore [id]        Restore from backup (latest if no id)
+--restore-latest      Restore from most recent backup
+--cleanup-backups     Remove old backup sessions
+--keep <n>            Keep last n sessions (default: 10)
+--max-age <days>      Max session age in days (default: 30)
+--init-backups        Initialize backup directory structure
+--auto-gitignore      Auto-add .i18nkit to .gitignore
+```
+
+### Watch Options
+
+```text
+--watch               Watch mode for file changes
 ```
 
 ## Exit Codes

package/bin/commands/backup.js

@@ -0,0 +1,226 @@
+'use strict';
+
+/**
+ * @fileoverview CLI commands for backup management.
+ * @module commands/backup
+ */
+
+const backup = require('../core/backup');
+
+function formatDate(isoString) {
+  return new Date(isoString).toLocaleString();
+}
+
+function getSessionAgeString(session) {
+  const preview = backup.getCleanupPreview(process.cwd());
+  const found = preview.toKeep.find(s => s.id === session.id);
+  const hasAge = found?.age !== undefined;
+  return hasAge ? `${found.age}d` : '';
+}
+
+function formatSessionRow(session) {
+  const status = session.status.padEnd(12);
+  const files = String(session.fileCount).padStart(3);
+  const age = getSessionAgeString(session).padStart(4);
+  return `${session.id} | ${status} | ${files} | ${age} | ${session.command || ''}`;
+}
+
+function logListHeader(log) {
+  log('\nBackup Sessions:');
+  log('-'.repeat(100));
+  log('ID                                    | Status       | Files | Age  | Command');
+  log('-'.repeat(100));
+}
+
+function logListFooter(sessions, log) {
+  log('-'.repeat(100));
+  log(`Total: ${sessions.length} sessions\n`);
+  const latestId = backup.Session.getLatestId(process.cwd());
+  if (latestId) {
+    log(`Latest: ${latestId}`);
+  }
+}
+
+function listBackups(ctx) {
+  const { cwd, log } = ctx;
+  const sessions = backup.listBackupSessions(cwd);
+  if (sessions.length === 0) {
+    log('No backup sessions found');
+    return;
+  }
+  logListHeader(log);
+  sessions.forEach(session => log(formatSessionRow(session)));
+  logListFooter(sessions, log);
+}
+
+function logInfoHeader(manifest, log) {
+  log('\nSession Details:');
+  log('-'.repeat(60));
+  log(`ID:        ${manifest.id}`);
+  log(`Status:    ${manifest.status}`);
+  log(`Command:   ${manifest.command}`);
+  log(`Timestamp: ${formatDate(manifest.timestamp)}`);
+  log(`Files:     ${manifest.files.length}`);
+  log('-'.repeat(60));
+}
+
+function logInfoFiles(files, log) {
+  if (files.length > 0) {
+    log('\nBacked Up Files:');
+    files.forEach(file => log(`  ${file.original} (${file.size} bytes)`));
+  }
+}
+
+function showBackupInfo(ctx) {
+  const { cwd, sessionId, log } = ctx;
+  const session = backup.getBackupSession(cwd, sessionId);
+  if (!session) {
+    log(`Session not found: ${sessionId}`);
+    return;
+  }
+  const { manifest } = session;
+  logInfoHeader(manifest, log);
+  logInfoFiles(manifest.files, log);
+  if (manifest.error) {
+    log(`\nError: ${manifest.error.message}`);
+  }
+}
+
+function logRestoreResult(result, log) {
+  log(`\nRestored: ${result.restored} files`);
+  if (result.skipped > 0) {
+    log(`Skipped:  ${result.skipped} files`);
+  }
+}
+
+function restoreBackup(ctx) {
+  const { cwd, sessionId, dryRun, verbose, log } = ctx;
+  const targetId = sessionId || backup.Session.getLatestId(cwd);
+  if (!targetId) {
+    log('No backup sessions found');
+    return;
+  }
+  const prefix = dryRun ? '[DRY RUN] Would restore' : 'Restoring';
+  log(`\n${prefix} from: ${targetId}`);
+  const result = backup.restoreSession(cwd, targetId, { dryRun, verbose, log });
+  logRestoreResult(result, log);
+}
+
+function logCleanupPreview(preview, log) {
+  log('\nCleanup Preview:');
+  log(`Would keep:   ${preview.toKeep.length} sessions`);
+  log(`Would delete: ${preview.toDelete.length} sessions`);
+  if (preview.toDelete.length > 0) {
+    log('\nSessions to delete:');
+    preview.toDelete.forEach(s => log(`  ${s.id} (${s.age} days old, ${s.fileCount} files)`));
+  }
+}
+
+function logCleanupResult(result, log) {
+  log(`\nDeleted: ${result.deleted} sessions`);
+  log(`Kept:    ${result.kept} sessions`);
+}
+
+function cleanupBackups(ctx) {
+  const { cwd, maxSessions = 10, maxAgeDays = 30, dryRun, verbose, log } = ctx;
+  if (dryRun) {
+    const preview = backup.getCleanupPreview(cwd, { maxSessions, maxAgeDays });
+    logCleanupPreview(preview, log);
+    return;
+  }
+  const result = backup.cleanupOldSessions(cwd, { maxSessions, maxAgeDays, verbose, log });
+  logCleanupResult(result, log);
+}
+
+function initBackupStructure(ctx) {
+  const { cwd, autoAddGitignore = false, verbose, log } = ctx;
+  const result = backup.initializeBackupStructure(cwd, { autoAddGitignore, verbose, log });
+  log('\nBackup structure initialized');
+  if (result.suggestion) {
+    log(`\nTip: ${result.suggestion.message}`);
+  }
+}
+
+function parseSessionIdArg(args, flagIndex) {
+  const nextArg = args[flagIndex + 1];
+  const isValidArg = nextArg && !nextArg.startsWith('--');
+  return isValidArg ? nextArg : null;
+}
+
+function parseIntArg(args, flag, defaultValue) {
+  const idx = args.indexOf(flag);
+  const hasFlag = idx !== -1;
+  return hasFlag ? parseInt(args[idx + 1], 10) : defaultValue;
+}
+
+const HANDLERS = {
+  '--list-backups': (_args, ctx) => listBackups(ctx),
+  '--backup-info': (args, ctx) => {
+    const sessionId = parseSessionIdArg(args, args.indexOf('--backup-info'));
+    if (!sessionId) {
+      ctx.log('Usage: i18nkit --backup-info <session-id>');
+      return undefined;
+    }
+    return showBackupInfo({ ...ctx, sessionId });
+  },
+  '--restore': (args, ctx) => {
+    const sessionId = parseSessionIdArg(args, args.indexOf('--restore'));
+    return restoreBackup({ ...ctx, sessionId });
+  },
+  '--cleanup-backups': (args, ctx) => {
+    const maxSessions = parseIntArg(args, '--keep', 10);
+    const maxAgeDays = parseIntArg(args, '--max-age', 30);
+    return cleanupBackups({ ...ctx, maxSessions, maxAgeDays });
+  },
+  '--init-backups': (args, ctx) => {
+    const autoAddGitignore = args.includes('--auto-gitignore');
+    return initBackupStructure({ ...ctx, autoAddGitignore });
+  },
+};
+
+function handleBackupCommand(args, ctx) {
+  const cwd = ctx.cwd || process.cwd();
+  const log = ctx.log || console.log;
+  const baseCtx = {
+    cwd,
+    log,
+    dryRun: args.includes('--dry-run'),
+    verbose: args.includes('--verbose'),
+    args,
+  };
+  for (const [flag, handler] of Object.entries(HANDLERS)) {
+    if (args.includes(flag)) {
+      return handler(args, baseCtx);
+    }
+  }
+  return undefined;
+}
+
+function isBackupCommand(args) {
+  return Object.keys(HANDLERS).some(cmd => args.includes(cmd));
+}
+
+module.exports = {
+  name: 'backup',
+  aliases: ['--list-backups', '--restore', '--cleanup-backups', '--backup-info', '--init-backups'],
+  category: 'maintenance',
+  description: 'Manage backup sessions and restore files',
+  options: [
+    { flag: '--list-backups', description: 'List all backup sessions' },
+    { flag: '--backup-info <id>', description: 'Show backup session details' },
+    { flag: '--restore [id]', description: 'Restore from backup (latest if no id)' },
+    { flag: '--cleanup-backups', description: 'Remove old backup sessions' },
+    { flag: '--keep <n>', description: 'Keep last n sessions (default: 10)' },
+    { flag: '--max-age <days>', description: 'Max age in days (default: 30)' },
+    { flag: '--init-backups', description: 'Initialize backup structure' },
+    { flag: '--auto-gitignore', description: 'Auto-add to .gitignore' },
+  ],
+  examples: [
+    'i18nkit --list-backups',
+    'i18nkit --restore',
+    'i18nkit --cleanup-backups --keep 5 --dry-run',
+  ],
+  run: ctx => handleBackupCommand(ctx.args, ctx),
+  isBackupCommand,
+  handleBackupCommand,
+};

package/bin/commands/extract.js

@@ -109,8 +109,8 @@ async function loadMergeResult(ctx) {
 }
 
 function getAutoApplyOpts(ctx) {
-  const { srcDir, backupDir, adapter, backup, dryRun, verbose, interactive, log } = ctx;
-  return { srcDir, backupDir, adapter, backup, dryRun, verbose, interactive, log };
+  const { srcDir, backupDir, reportDir, adapter, backup, dryRun, verbose, interactive, log } = ctx;
+  return { srcDir, backupDir, reportDir, adapter, backup, dryRun, verbose, interactive, log };
 }
 
 async function runAutoApply(findings, ctx) {

package/bin/core/applier-utils.js

@@ -2,7 +2,7 @@
 
 const fs = require('./fs-adapter');
 const readline = require('readline');
-const { createBackup, getBackupFiles } = require('./backup');
+const { getBackupFiles } = require('./backup');
 
 const isValidFinding = f => f.file && f.text && f.key && !f.context?.startsWith('ts_');
 
@@ -68,12 +68,12 @@ function applyReplacementsToContent(content, fileFindings, adapter) {
   let result = content;
   let count = 0;
   for (const finding of fileFindings) {
-    const transformed = adapter.transform(
-      result,
-      finding.rawText || finding.text,
-      finding.key,
-      finding.context,
-    );
+    const transformed = adapter.transform({
+      content: result,
+      rawText: finding.rawText || finding.text,
+      key: finding.key,
+      context: finding.context,
+    });
     result = transformed.content;
     count += transformed.replacements;
   }
@@ -81,8 +81,7 @@ function applyReplacementsToContent(content, fileFindings, adapter) {
 }
 
 function tryUpdateTsImports(tsFile, opts) {
-  const { backupDir, adapter, backup = true, dryRun = false } = opts;
-  createBackup(tsFile, backupDir, { enabled: backup, dryRun });
+  const { adapter, dryRun = false } = opts;
   const tsContent = fs.readFileSync(tsFile, 'utf-8');
   const updatedTs = adapter.updateImports(tsContent);
   if (updatedTs === tsContent) {