i18ntk 2.2.0 → 2.3.0

package/README.md

@@ -1,6 +1,6 @@
-# i18ntk v2.2.0
+# i18ntk v2.3.0
 
-Zero-dependency i18n toolkit for initialization, scanning, analysis, validation, usage tracking, and translation completion.
+Zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, and translation completion.
 
 ![i18ntk Logo](docs/screenshots/i18ntk-logo-public.PNG)
 
@@ -9,57 +9,76 @@ Zero-dependency i18n toolkit for initialization, scanning, analysis, validation,
 [![node](https://img.shields.io/badge/node-%3E%3D16-339933)](https://nodejs.org)
 [![dependencies](https://img.shields.io/badge/dependencies-0-success)](https://www.npmjs.com/package/i18ntk)
 [![license](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
-[![socket](https://socket.dev/api/badge/npm/package/i18ntk/2.2.0)](https://socket.dev/npm/package/i18ntk/overview/2.2.0)
+[![socket](https://socket.dev/api/badge/npm/package/i18ntk/2.3.0)](https://socket.dev/npm/package/i18ntk/overview/2.3.0)
 
 ## Upgrade Notice
 
-Versions earlier than `2.2.0` may contain known stability and security issues.
-They are considered unsupported for production use. Upgrade to `2.2.0` or newer.
+Versions earlier than `2.3.0` may contain known stability and security issues.
+They are considered unsupported for production use. Upgrade to `2.3.0` or newer.
 
-## Why i18ntk
+## What i18ntk Does
 
 - Zero runtime dependencies
-- Works across JS/TS, React, Vue, Angular, and generic projects
-- Supports non-interactive CI runs (`--no-prompt`)
-- Includes usage/coverage validation and missing-key completion
-- Ships with runtime translation helpers via `i18ntk/runtime`
+- Interactive and non-interactive project setup
+- Translation completeness analysis and usage tracking
+- Validation, sizing, and summary reporting
+- Missing-key completion and fixer workflows
+- Runtime translation helpers for application code
+- Support for JS/TS, React, Vue, Angular, and generic projects
+
+## Getting Started
+
+1. Install the package.
+2. Run `i18ntk` or `i18ntk --command=init` to initialize the project.
+3. Confirm the source language and locale directories.
+4. Run `i18ntk --command=analyze` or `i18ntk --command=validate` to inspect translation coverage.
+5. Use `i18ntk --command=complete` to fill missing keys when needed.
+
+The full onboarding flow is documented in [docs/getting-started.md](docs/getting-started.md).
 
 ## Install
 
 ```bash
-# global (recommended for CLI use)
+# global CLI use
 npm install -g i18ntk
 
-# local
+# local project use
 npm install --save-dev i18ntk
 
-# one-off
+# one-off execution
 npx i18ntk --help
 ```
 
-## Quick Start
+## Setup
+
+The toolkit stores project configuration in `.i18ntk-config` at the project root.
+
+Recommended setup flow:
 
 ```bash
-# initialize locales/project settings
+i18ntk
+# or
 i18ntk --command=init
+```
 
-# analyze translation completeness
-i18ntk --command=analyze
+During setup, you can define:
 
-# validate translation structure/content
-i18ntk --command=validate
+- source directory
+- source language
+- UI language
+- framework preference
+- output directory
+- backup behavior
 
-# complete missing keys
-i18ntk --command=complete
-```
+If you run in CI or a non-interactive shell, use:
 
-## Command Model (v2)
+```bash
+i18ntk --command=init --no-prompt
+```
 
-Primary CLI:
+## Daily Use
 
 ```bash
-i18ntk
-i18ntk --command=init
 i18ntk --command=analyze
 i18ntk --command=validate
 i18ntk --command=usage
@@ -67,10 +86,9 @@ i18ntk --command=scanner
 i18ntk --command=sizing
 i18ntk --command=complete
 i18ntk --command=summary
-i18ntk --command=debug
 ```
 
-Standalone executables:
+Standalone commands are also available:
 
 ```bash
 i18ntk-init
@@ -97,15 +115,43 @@ i18ntk-backup
 - `--dry-run`
 - `--help`
 
-## Configuration
+Example:
 
-i18ntk reads project settings from `.i18ntk-config` in your project root.
+```bash
+i18ntk --command=analyze --source-dir=./src --i18n-dir=./locales --output-dir=./i18ntk-reports
+```
 
-Example:
+## Runtime API
+
+Use `i18ntk/runtime` when your application needs to read locale JSON files at runtime.
+
+```js
+const runtime = require('i18ntk/runtime');
+
+runtime.initRuntime({
+  baseDir: './locales',
+  language: 'en',
+  fallbackLanguage: 'en',
+  keySeparator: '.',
+  preload: true
+});
+
+console.log(runtime.t('common.hello'));
+runtime.setLanguage('fr');
+console.log(runtime.getLanguage());
+console.log(runtime.getAvailableLanguages());
+runtime.refresh('fr');
+```
+
+For a deeper walkthrough, see [docs/runtime.md](docs/runtime.md).
+
+## Configuration
+
+Example `.i18ntk-config`:
 
 ```json
 {
-  "version": "2.2.0",
+  "version": "2.3.0",
   "sourceDir": "./locales",
   "i18nDir": "./locales",
   "outputDir": "./i18ntk-reports",
@@ -117,32 +163,19 @@ Example:
 }
 ```
 
-## Runtime API
-
-```ts
-import { initRuntime, t, setLanguage, getLanguage } from 'i18ntk/runtime';
-
-initRuntime({
-  baseDir: './locales',
-  language: 'en',
-  fallbackLanguage: 'en',
-  preload: true
-});
-
-console.log(t('common.hello'));
-setLanguage('fr');
-console.log(getLanguage());
-```
+See [docs/api/CONFIGURATION.md](docs/api/CONFIGURATION.md) for the full configuration model.
 
-## Documentation
+## Docs
 
 - [Documentation Index](docs/README.md)
+- [Getting Started](docs/getting-started.md)
 - [API Reference](docs/api/API_REFERENCE.md)
 - [Configuration Guide](docs/api/CONFIGURATION.md)
 - [Runtime API Guide](docs/runtime.md)
 - [Scanner Guide](docs/scanner-guide.md)
 - [Environment Variables](docs/environment-variables.md)
-- [Migration Guide v2.2.0](docs/migration-guide-v2.2.0.md)
+- [Migration Guide v2.3.0](docs/migration-guide-v2.3.0.md)
+- [Optimization Prompt](docs/development/package-optimization-prompt.md)
 
 ## License
 

package/main/i18ntk-backup-class.js

@@ -2,12 +2,12 @@
 
 'use strict';
 
-const fs = require('fs/promises');
-const path = require('path');
-const { existsSync } = require('fs');
-const configManager = require('../utils/config-manager');
-const { logger } = require('../utils/logger');
-const { colors } = require('../utils/logger');
+const fs = require('fs');
+const fsp = fs.promises;
+const path = require('path');
+const configManager = require('../utils/config-manager');
+const { logger } = require('../utils/logger');
+const { colors } = require('../utils/logger');
 const SecurityUtils = require('../utils/security');
 
 /**
@@ -16,10 +16,10 @@ const SecurityUtils = require('../utils/security');
  * Class-based implementation of backup functionality for use with CommandRouter
  */
 class I18nBackup {
-    constructor(config = {}) {
-        this.config = config;
-        this.backupDir = path.join(process.cwd(), 'i18n-backups');
-        this.maxBackups = config.backup?.maxBackups || 10;
+    constructor(config = {}) {
+        this.config = config;
+        this.backupDir = path.join(process.cwd(), 'i18ntk-backups');
+        this.maxBackups = Math.min(Math.max(parseInt(config.backup?.maxBackups, 10) || 1, 1), 3);
     }
 
     /**
@@ -93,7 +93,7 @@ Options:
 
         // Create backup directory if it doesn't exist
         try {
-            await fs.mkdir(outputDir, { recursive: true });
+            await fsp.mkdir(outputDir, { recursive: true });
             logger.debug(`Created backup directory: ${outputDir}`);
         } catch (err) {
             if (err.code !== 'EEXIST') {
@@ -106,7 +106,7 @@ Options:
         // Validate directory
         const sourceDir = path.resolve(dir);
         try {
-            const stats = await fs.stat(sourceDir);
+            const stats = await fsp.stat(sourceDir);
             if (!stats.isDirectory()) {
                 throw new Error(`Path exists but is not a directory: ${sourceDir}`);
             }
@@ -121,7 +121,7 @@ Options:
         logger.info('\nCreating backup...');
 
         // Read all files in the directory
-        const files = (await fs.readdir(sourceDir, { withFileTypes: true }))
+        const files = (await fsp.readdir(sourceDir, { withFileTypes: true }))
             .filter(dirent => dirent.isFile() && dirent.name.endsWith('.json'))
             .map(dirent => dirent.name);
 
@@ -135,7 +135,7 @@ Options:
         for (const file of files) {
             const filePath = path.join(sourceDir, file);
             try {
-                const content = JSON.parse(await fs.readFile(filePath, 'utf8'));
+                const content = JSON.parse(await fsp.readFile(filePath, 'utf8'));
                 translations[file] = content;
             } catch (error) {
                 logger.error(`Could not read file ${file}: ${error.message}`);
@@ -143,8 +143,8 @@ Options:
         }
 
         // Create the backup
-        await fs.writeFile(backupPath, JSON.stringify(translations, null, 2));
-        const stats = await fs.stat(backupPath);
+        await fsp.writeFile(backupPath, JSON.stringify(translations, null, 2));
+        const stats = await fsp.stat(backupPath);
 
         logger.success('Backup created successfully');
         logger.info(`  Location: ${backupPath}`);
@@ -218,7 +218,7 @@ Options:
         try {
             // Ensure backup directory exists
             try {
-                await fs.access(this.backupDir);
+                await fsp.access(this.backupDir);
             } catch (err) {
                 if (err.code === 'ENOENT') {
                     logger.warn('No backups found. The backup directory does not exist yet.');
@@ -228,14 +228,14 @@ Options:
                 return { success: true, backups: [] };
             }
 
-            const files = await fs.readdir(this.backupDir);
+            const files = await fsp.readdir(this.backupDir);
             const backups = [];
 
             for (const file of files) {
                 if (file.startsWith('backup-') && file.endsWith('.json')) {
                     try {
                         const filePath = path.join(this.backupDir, file);
-                        const stats = await fs.stat(filePath);
+                        const stats = await fsp.stat(filePath);
                         backups.push({
                             name: file,
                             path: filePath,
@@ -298,14 +298,14 @@ Options:
         logger.info('\nVerifying backup...');
 
         try {
-            const data = await fs.readFile(backupPath, 'utf8');
+            const data = await fsp.readFile(backupPath, 'utf8');
             const content = JSON.parse(data);
 
             if (typeof content === 'object' && content !== null) {
                 const fileCount = Object.keys(content).length;
                 logger.success('Backup is valid');
                 logger.info(`  Contains ${fileCount} translation files`);
-                logger.info(`  Last modified: ${(await fs.stat(backupPath)).mtime.toLocaleString()}`);
+                logger.info(`  Last modified: ${(await fsp.stat(backupPath)).mtime.toLocaleString()}`);
 
                 return {
                     success: true,
@@ -334,14 +334,14 @@ Options:
         logger.info('\nCleaning up old backups...');
 
         try {
-            const files = await fs.readdir(this.backupDir);
+            const files = await fsp.readdir(this.backupDir);
             const backupFiles = files
                 .filter(file => file.startsWith('backup-') && file.endsWith('.json'))
                 .map(file => ({
                     name: file,
-                    path: path.join(this.backupDir, file),
-                    time: fs.statSync(path.join(this.backupDir, file)).mtime.getTime()
-                }))
+                    path: path.join(this.backupDir, file),
+                    time: fs.statSync(path.join(this.backupDir, file)).mtime.getTime()
+                }))
                 .sort((a, b) => b.time - a.time);
 
             // Keep only the most recent 'keep' files
@@ -355,7 +355,7 @@ Options:
             // Delete old backups
             for (const file of toDelete) {
                 try {
-                    await fs.unlink(file.path);
+                    await fsp.unlink(file.path);
                     logger.info(`  - Deleted: ${file.name}`);
                 } catch (err) {
                     logger.error(`  - Failed to delete ${file.name}: ${err.message}`);
@@ -374,12 +374,10 @@ Options:
         } catch (error) {
             logger.error('Error cleaning up backups:');
             logger.error(`  ${error.message}`);
-            if (process.env.DEBUG) {
-                console.error(error);
-            }
-            throw error;
-        }
-    }
+            logger.debug(error.stack || error.message);
+            throw error;
+        }
+    }
 
     async cleanupOldBackups(outputDir) {
         try {
@@ -408,13 +406,11 @@ Options:
         }
     }
 
-    handleError(error) {
-        logger.error('Backup operation failed:');
-        logger.error(`  ${error.message}`);
-        if (process.env.DEBUG) {
-            console.error(error);
-        }
-    }
-}
+    handleError(error) {
+        logger.error('Backup operation failed:');
+        logger.error(`  ${error.message}`);
+        logger.debug(error.stack || error.message);
+    }
+}
 
-module.exports = I18nBackup;
+module.exports = I18nBackup;

package/main/i18ntk-backup.js

@@ -2,7 +2,8 @@
 
 'use strict';
 
-const fs = require('fs/promises');
+const fs = require('fs');
+const fsp = fs.promises;
 const path = require('path');
 
 // Simple CLI argument parser
@@ -36,16 +37,15 @@ function parseArgs(args) {
 
   return result;
 }
-const { existsSync } = require('fs');
-const configManager = require('../utils/config-manager');
-const { logger } = require('../utils/logger');
-const { colors } = require('../utils/logger');
+const configManager = require('../utils/config-manager');
+const { logger } = require('../utils/logger');
+const { colors } = require('../utils/logger');
 const prompt = require('../utils/prompt');
 
 // Backup configuration
 const config = configManager.getConfig();
-const backupDir = path.join(process.cwd(), 'i18n-backups');
-const maxBackups = config.backup?.maxBackups || 10;
+const backupDir = path.join(process.cwd(), 'i18ntk-backups');
+const maxBackups = Math.min(Math.max(parseInt(config.backup?.maxBackups, 10) || 1, 1), 3);
 
 // Main function to handle commands
 async function main() {
@@ -121,7 +121,7 @@ async function handleCreate(args) {
 
   // Create backup directory if it doesn't exist
   try {
-    await fs.mkdir(outputDir, { recursive: true });
+    await fsp.mkdir(outputDir, { recursive: true });
     logger.debug(`Created backup directory: ${outputDir}`);
   } catch (err) {
     if (err.code !== 'EEXIST') {
@@ -134,7 +134,7 @@ async function handleCreate(args) {
   // Validate directory
   const sourceDir = path.resolve(dir);
   try {
-    const stats = await fs.stat(sourceDir);
+    const stats = await fsp.stat(sourceDir);
     if (!stats.isDirectory()) {
       throw new Error(`Path exists but is not a directory: ${sourceDir}`);
     }
@@ -149,7 +149,7 @@ async function handleCreate(args) {
   logger.info('\nCreating backup...');
   
   // Read all files in the directory
-  const files = (await fs.readdir(sourceDir, { withFileTypes: true }))
+  const files = (await fsp.readdir(sourceDir, { withFileTypes: true }))
     .filter(dirent => dirent.isFile() && dirent.name.endsWith('.json'))
     .map(dirent => dirent.name);
     
@@ -163,7 +163,7 @@ async function handleCreate(args) {
   for (const file of files) {
     const filePath = path.join(sourceDir, file);
     try {
-      const content = JSON.parse(await fs.readFile(filePath, 'utf8'));
+      const content = JSON.parse(await fsp.readFile(filePath, 'utf8'));
       translations[file] = content;
     } catch (error) {
       logger.error(`Could not read file ${file}: ${error.message}`);
@@ -171,8 +171,8 @@ async function handleCreate(args) {
   }
   
   // Create the backup
-  await fs.writeFile(backupPath, JSON.stringify(translations, null, 2));
-  const stats = await fs.stat(backupPath);
+  await fsp.writeFile(backupPath, JSON.stringify(translations, null, 2));
+  const stats = await fsp.stat(backupPath);
   
   logger.success('Backup created successfully');
   logger.info(`  Location: ${backupPath}`);
@@ -203,12 +203,12 @@ async function handleRestore(args) {
   
   try {
     // Read the backup file
-    const backupData = await fs.readFile(backupPath, 'utf8');
+    const backupData = await fsp.readFile(backupPath, 'utf8');
     const translations = JSON.parse(backupData);
     
     // Create output directory if it doesn't exist
     try {
-      await fs.mkdir(outputDir, { recursive: true });
+      await fsp.mkdir(outputDir, { recursive: true });
     } catch (err) {
       if (err.code !== 'EEXIST') throw err;
     }
@@ -216,7 +216,7 @@ async function handleRestore(args) {
     // Write the restored files
     for (const [file, content] of Object.entries(translations)) {
       const filePath = path.join(outputDir, file);
-      await fs.writeFile(filePath, JSON.stringify(content, null, 2));
+      await fsp.writeFile(filePath, JSON.stringify(content, null, 2));
     }
     
     logger.success('Backup restored successfully');
@@ -230,7 +230,7 @@ async function handleList() {
   try {
     // Ensure backup directory exists
     try {
-      await fs.access(backupDir);
+      await fsp.access(backupDir);
     } catch (err) {
       if (err.code === 'ENOENT') {
         logger.warn('No backups found. The backup directory does not exist yet.');
@@ -240,14 +240,14 @@ async function handleList() {
       return;
     }
 
-    const files = await fs.readdir(backupDir);
+    const files = await fsp.readdir(backupDir);
     const backups = [];
     
     for (const file of files) {
       if (file.startsWith('backup-') && file.endsWith('.json')) {
         try {
           const filePath = path.join(backupDir, file);
-          const stats = await fs.stat(filePath);
+        const stats = await fsp.stat(filePath);
           backups.push({
             name: file,
             path: filePath,
@@ -307,14 +307,14 @@ async function handleVerify(args) {
   logger.info('\nVerifying backup...');
   
   try {
-    const data = await fs.readFile(backupPath, 'utf8');
+    const data = await fsp.readFile(backupPath, 'utf8');
     const content = JSON.parse(data);
     
     if (typeof content === 'object' && content !== null) {
       const fileCount = Object.keys(content).length;
       logger.success('Backup is valid');
       logger.info(`  Contains ${fileCount} translation files`);
-      logger.info(`  Last modified: ${(await fs.stat(backupPath)).mtime.toLocaleString()}`);
+      logger.info(`  Last modified: ${(await fsp.stat(backupPath)).mtime.toLocaleString()}`);
     } else {
       throw new Error('Invalid backup format');
     }
@@ -331,13 +331,13 @@ async function handleCleanup(args) {
   logger.info('\nCleaning up old backups...');
   
   try {
-    const files = await fs.readdir(backupDir);
+    const files = await fsp.readdir(backupDir);
     const backupFiles = files
       .filter(file => file.startsWith('backup-') && file.endsWith('.json'))
       .map(file => ({
         name: file,
         path: path.join(backupDir, file),
-        time: fs.statSync(path.join(backupDir, file)).mtime.getTime()
+        time: fs.statSync(path.join(backupDir, file)).mtime.getTime()
       }))
       .sort((a, b) => b.time - a.time);
     
@@ -352,7 +352,7 @@ async function handleCleanup(args) {
     // Delete old backups
     for (const file of toDelete) {
       try {
-        await fs.unlink(file.path);
+        await fsp.unlink(file.path);
         logger.info(`  - Deleted: ${file.name}`);
       } catch (err) {
         logger.error(`  - Failed to delete ${file.name}: ${err.message}`);
@@ -365,12 +365,10 @@ async function handleCleanup(args) {
   } catch (error) {
     logger.error('Error cleaning up backups:');
     logger.error(`  ${error.message}`);
-    if (process.env.DEBUG) {
-      console.error(error);
-    }
-    process.exit(1);
-  }
-}
+    logger.debug(error.stack || error.message);
+    process.exit(1);
+  }
+}
 
 // Start the application
 // Handle unhandled promise rejections

package/main/i18ntk-doctor.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
-const SecurityUtils = require('../utils/security');
-const fs = require('fs');
-const path = require('path');
-const { getUnifiedConfig, parseCommonArgs, displayHelp } = require('../utils/config-helper');
+const SecurityUtils = require('../utils/security');
+const fs = require('fs');
+const path = require('path');
+const packageJson = require('../package.json');
+const { getUnifiedConfig, parseCommonArgs, displayHelp } = require('../utils/config-helper');
 const SetupEnforcer = require('../utils/setup-enforcer');
 
 // Ensure setup is complete before running (only for standalone execution)
@@ -97,7 +98,7 @@ class I18nDoctor {
       }
     }
 
-    const pkgVersion = require('../package.json').version;
+    const pkgVersion = packageJson.version;
     if (config.version && config.version !== pkgVersion) {
       issues.push(`Config version mismatch: ${config.version} != ${pkgVersion}`);
       exitCode = Math.max(exitCode, ExitCodes.CONFIG_ERROR);
@@ -181,4 +182,4 @@ if (require.main === module) {
   doctor.run();
 }
 
-module.exports = I18nDoctor;
+module.exports = I18nDoctor;

package/main/i18ntk-init.js

@@ -754,7 +754,7 @@ class I18nInitializer {
   }
 
   // Interactive admin PIN setup
-  async promptAdminPinSetup() {
+  async promptAdminPinSetup() {
     const { ask, askHidden, flushStdout } = require('../utils/cli');
 
     console.log('\n' + t('init.adminPinSetupOptional'));
@@ -806,8 +806,31 @@ class I18nInitializer {
       }
     } else {
       console.log(t('init.skippingAdminPinSetup'));
-    }
-  }
+    }
+  }
+
+  async promptBackupConfiguration(skipPrompt = false) {
+    const defaultBackupConfig = { enabled: false, maxBackups: 1, location: './i18ntk-backups' };
+    if (skipPrompt || !isInteractive()) {
+      return null;
+    }
+
+    const { ask } = require('../utils/cli');
+    console.log('\nBackup Settings');
+    console.log('Backups are disabled by default to avoid backup recursion and repo pollution.');
+    const enableAnswer = await ask('Enable automatic backups? (y/N): ');
+    const enabled = ['y', 'yes'].includes(String(enableAnswer || '').trim().toLowerCase());
+
+    if (!enabled) {
+      return defaultBackupConfig;
+    }
+
+    const keepAnswer = await ask('How many backups should be kept automatically (1-3, default 1): ');
+    const parsedKeep = parseInt(String(keepAnswer || '').trim(), 10);
+    const maxBackups = Number.isInteger(parsedKeep) ? Math.min(Math.max(parsedKeep, 1), 3) : 1;
+
+    return { enabled: true, maxBackups, location: './i18ntk-backups' };
+  }
 
   // Interactive language selection
   async selectLanguages(skipPrompt = false) {
@@ -921,11 +944,24 @@ class I18nInitializer {
     // Prompt for admin PIN setup if not already configured
     const securitySettings = configManager.getConfig().security || {};
     
-    if (!securitySettings.adminPinEnabled && securitySettings.adminPinPromptOnInit !== false && !args.noPrompt) {
-      const { flushStdout } = require('../utils/cli');
-      await flushStdout();
-      await this.promptAdminPinSetup();
-    }
+    if (!securitySettings.adminPinEnabled && securitySettings.adminPinPromptOnInit !== false && !args.noPrompt) {
+      const { flushStdout } = require('../utils/cli');
+      await flushStdout();
+      await this.promptAdminPinSetup();
+    }
+
+    const backupSettings = await this.promptBackupConfiguration(args.noPrompt);
+    if (backupSettings) {
+      await configManager.updateConfig({
+        backup: {
+          ...(this.config.backup || {}),
+          ...backupSettings
+        }
+      });
+      this.config.backup = { ...(this.config.backup || {}), ...backupSettings };
+    } else if (!this.config.backup) {
+      this.config.backup = { enabled: false, maxBackups: 1, location: './i18ntk-backups' };
+    }
 
     // Get target languages - use args.languages if provided
     let targetLanguages = args.languages || await this.selectLanguages(args.noPrompt);