i18ntk 2.3.1 → 2.3.4

package/README.md

@@ -1,4 +1,4 @@
-# i18ntk v2.3.1
+# i18ntk v2.3.4
 
 Zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, and translation completion.
 
@@ -9,12 +9,15 @@ Zero-dependency internationalization toolkit for setup, scanning, analysis, vali
 [![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.3.1)](https://socket.dev/npm/package/i18ntk/overview/2.3.1)
+[![socket](https://socket.dev/api/badge/npm/package/i18ntk/2.3.4)](https://socket.dev/npm/package/i18ntk/overview/2.3.4)
 
 ## Upgrade Notice
 
-Versions earlier than `2.3.1` may contain known stability and security issues.
-They are considered unsupported for production use. Upgrade to `2.3.1` or newer.
+Versions earlier than `2.3.4` may contain known stability and security issues.
+They are considered unsupported for production use. Upgrade to `2.3.4` or newer.
+The CLI now checks npm registry metadata at startup and warns when your installed version is out of date.
+Set `I18NTK_DISABLE_UPDATE_CHECK=true` to disable this warning in restricted/offline environments.
+Set `I18NTK_DISABLE_AUTOSAVE=1` in server/runtime environments to keep config in memory and skip disk writes.
 
 ## What i18ntk Does
 
@@ -151,7 +154,7 @@ Example `.i18ntk-config`:
 
 ```json
 {
-  "version": "2.3.1",
+  "version": "2.3.4",
   "sourceDir": "./locales",
   "i18nDir": "./locales",
   "outputDir": "./i18ntk-reports",
@@ -174,7 +177,7 @@ See [docs/api/CONFIGURATION.md](docs/api/CONFIGURATION.md) for the full configur
 - [Runtime API Guide](docs/runtime.md)
 - [Scanner Guide](docs/scanner-guide.md)
 - [Environment Variables](docs/environment-variables.md)
-- [Migration Guide v2.3.1](docs/migration-guide-v2.3.1.md)
+- [Migration Guide v2.3.4](docs/migration-guide-v2.3.4.md)
 - [Optimization Prompt](docs/development/package-optimization-prompt.md)
 
 ## License

package/main/manage/commands/AnalyzeCommand.js

@@ -7,10 +7,11 @@
  * Contains embedded business logic from I18nAnalyzer.
  */
 
+const fs = require('fs');
 const path = require('path');
 const cliHelper = require('../../../utils/cli-helper');
 const { loadTranslations, t } = require('../../../utils/i18n-helper');
-const { getUnifiedConfig, parseCommonArgs, displayHelp } = require('../../../utils/config-helper');
+const { getUnifiedConfig, parseCommonArgs, displayHelp, validateSourceDir } = require('../../../utils/config-helper');
 const SecurityUtils = require('../../../utils/security');
 const AdminCLI = require('../../../utils/admin-cli');
 const AdminAuth = require('../../../utils/admin-auth');
@@ -21,7 +22,7 @@ loadTranslations('en', path.resolve(__dirname, '../../../ui-locales'));
 
 const PROJECT_ROOT = process.cwd();
 
-class AnalyzeCommand {
+class AnalyzeCommand {
     constructor(config = {}, ui = null) {
         this.config = config;
         this.ui = ui;
@@ -44,11 +45,11 @@ class AnalyzeCommand {
         this.safeClose = safeClose;
     }
 
-    /**
-     * Initialize the analyzer with configuration
-     */
-    async initialize() {
-        try {
+    /**
+     * Initialize the analyzer with configuration
+     */
+    async initialize() {
+        try {
             const args = this.parseArgs();
             if (args.help) {
                 displayHelp('i18ntk-analyze', {
@@ -78,17 +79,62 @@ class AnalyzeCommand {
             loadTranslations(uiLanguage, path.resolve(__dirname, '../../../ui-locales'));
 
             this.sourceDir = this.config.sourceDir;
-            this.sourceLanguageDir = path.join(this.sourceDir, this.config.sourceLanguage);
-            this.outputDir = this.config.outputDir;
-
-            // Validate source directory exists
-            validateSourceDir(this.sourceDir, 'i18ntk-analyze');
-
-        } catch (error) {
-            console.error(`Fatal analysis error: ${error.message}`);
-            throw error;
-        }
-    }
+            this.sourceLanguageDir = path.join(this.sourceDir, this.config.sourceLanguage);
+            this.outputDir = this.config.outputDir;
+
+            // Validate source directory exists and is readable/writable
+            this.validateSourceDirWithFallback(this.sourceDir);
+
+        } catch (error) {
+            SecurityUtils.logSecurityEvent('Analyze command initialization failed', 'error', {
+                component: 'AnalyzeCommand',
+                error: error.message
+            });
+            console.error(`Fatal analysis error: ${error.message}`);
+            throw error;
+        }
+    }
+
+    /**
+     * Validate source directory with fallback logic if the shared helper is unavailable.
+     * This prevents runtime crashes from missing imports or module regressions.
+     * @param {string} sourceDir
+     */
+    validateSourceDirWithFallback(sourceDir) {
+        if (!sourceDir || typeof sourceDir !== 'string') {
+            throw new Error('Source directory is missing or invalid');
+        }
+
+        if (typeof validateSourceDir === 'function') {
+            validateSourceDir(sourceDir, 'i18ntk-analyze');
+        } else {
+            // Graceful fallback: create directory if needed.
+            const created = SecurityUtils.safeMkdirSync(sourceDir, process.cwd(), { recursive: true });
+            if (created) {
+                SecurityUtils.logSecurityEvent('Fallback source directory creation executed', 'warn', {
+                    component: 'AnalyzeCommand',
+                    sourceDir,
+                    reason: 'validateSourceDir helper unavailable'
+                });
+            }
+        }
+
+        const safePath = SecurityUtils.validatePath(sourceDir, process.cwd());
+        if (!safePath) {
+            throw new Error(`Source directory path is unsafe: ${sourceDir}`);
+        }
+
+        const stat = SecurityUtils.safeStatSync(safePath, process.cwd());
+        if (!stat || !stat.isDirectory()) {
+            throw new Error(`Source directory does not exist or is not a directory: ${safePath}`);
+        }
+
+        try {
+            fs.accessSync(safePath, fs.constants.R_OK | fs.constants.W_OK);
+        } catch {
+            throw new Error(`Insufficient permissions for source directory: ${safePath}`);
+        }
+    }
 
     // Initialize readline interface (deprecated - use cliHelper directly)
     initReadline() {

package/main/manage/index.js

@@ -24,6 +24,7 @@ const { showFrameworkWarningOnce } = require('../../utils/cli-helper');
 const { createPrompt, isInteractive } = require('../../utils/prompt-helper');
 const { loadTranslations, t, refreshLanguageFromSettings} = require('../../utils/i18n-helper');
 const cliHelper = require('../../utils/cli-helper');
+const { printUpgradeWarningIfOutdated } = require('../../utils/npm-version-warning');
 const { blue } = require('../../utils/colors-new');
 const { loadConfig, saveConfig, ensureConfigDefaults } = require('../../utils/config');
 const SettingsCLI = require('../../settings/settings-cli');
@@ -315,10 +316,20 @@ class I18nManager {
         // Show help immediately without any setup/auth (useful for CI/uninitialized projects)
         if (args.help) {
             this.showHelp();
-            return;
-        }
-
-        let startupTimeout = setTimeout(() => {
+            return;
+        }
+
+        // Warn users when their installed CLI version is behind npm latest.
+        try {
+            await printUpgradeWarningIfOutdated({
+                packageName: pkg.name,
+                currentVersion: pkg.version
+            });
+        } catch {
+            // Keep startup resilient if registry access is unavailable.
+        }
+
+        let startupTimeout = setTimeout(() => {
             console.error('❌ CLI startup timeout - something is hanging');
             process.exit(1);
         }, 10000); // 10 second timeout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18ntk",
-  "version": "2.3.1",
+  "version": "2.3.4",
   "description": "🚀 The fastest internationalization toolkit with 97% performance boost! Zero-dependency, enterprise-grade internationalization for React, Vue, Angular, Python, Java, PHP & more. Features PIN protection, auto framework detection, 7+ UI languages, and comprehensive translation management. Perfect for startups to enterprises.",
   "keywords": [
     "i18n",
@@ -227,7 +227,7 @@
   },
   "preferGlobal": true,
   "versionInfo": {
-    "version": "2.3.1",
+    "version": "2.3.4",
     "releaseDate": "12/04/2026",
     "lastUpdated": "12/04/2026",
     "maintainer": "Vlad Noskov",
@@ -238,7 +238,10 @@
       "HOTFIX: Removed deprecated package-path fallback that caused production build warnings for non-exported subpaths.",
       "CRITICAL FIX: Resolved sizing and usage-analysis regressions in v2 command flow.",
       "PACKAGING: Reduced publish footprint by removing internal development scripts and legacy fixed-file artifacts.",
-      "SECURITY: Hardened release checks and added explicit support guidance to update from pre-2.3.1 versions.",
+      "SECURITY: Hardened release checks and added explicit support guidance to update from pre-2.3.4 versions.",
+      "CONFIG: Added cross-process file locking for .i18ntk-config writes to prevent production rename races.",
+      "CONFIG: Made autosave runtime-safe with non-throwing save failures and I18NTK_DISABLE_AUTOSAVE support.",
+      "CLI: Added npm registry version check with upgrade warning for out-of-date installs.",
       "I18N: Completed internal UI locale parity and actionable untranslated-key cleanup across supported languages."
     ],
     "breakingChanges": [],
@@ -264,7 +267,7 @@
       "spring-boot": ">=2.5.0",
       "laravel": ">=8.0.0"
     },
-    "supportPolicy": "Versions earlier than 2.3.1 may be unstable or insecure. Upgrade to 2.3.1 or newer."
+    "supportPolicy": "Versions earlier than 2.3.4 may be unstable or insecure. Upgrade to 2.3.4 or newer."
   },
   "_comment": "This package is zero-dependency and uses only native Node.js modules"
 }

package/ui-locales/en.json

@@ -476,7 +476,7 @@
     "report_saved_to": "Report saved to: {reportPath}",
     "considerReviewingTranslations": "Consider reviewing ${lang} translations - they are ${data.percentageDifference}% longer than baseline",
     "csv_report_saved_to": "CSV report saved to: {csvPath}",
-    "human_report_saved": "Human-readable report saved: {reportPath}",
+    "human_report_saved": "Readable report saved: {reportPath}",
     "folder_summary_title": "Folder Summary",
     "folder_summary_table_header": "Language    Size(KB)    Keys    Avg Length    Total Chars",
     "folder_summary_row": "{lang}      {sizeKB}      {totalKeys}    {avgLength}    {totalChars}",

package/utils/config-manager.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const crypto = require('crypto');
 const SecurityUtils = require('./security');
 
 // Determine package directory and user project root
@@ -9,8 +10,13 @@ const userProjectRoot = process.cwd();
 
 // Always use current working directory for settings to support test environments
 // This ensures config works correctly when tests change the working directory
-const PROJECT_CONFIG_PATH = path.join(process.cwd(), '.i18ntk-config');
-const PROJECT_SETTINGS_DIR = path.dirname(PROJECT_CONFIG_PATH);
+const PROJECT_CONFIG_PATH = path.join(process.cwd(), '.i18ntk-config');
+const PROJECT_SETTINGS_DIR = path.dirname(PROJECT_CONFIG_PATH);
+const CONFIG_LOCK_PATH = `${PROJECT_CONFIG_PATH}.lock`;
+const CONFIG_LOCK_TIMEOUT_MS = 5000;
+const CONFIG_LOCK_STALE_MS = 15000;
+const CONFIG_LOCK_RETRY_MS = 50;
+let autosaveDisabledWarned = false;
 
 // Setup tracking file
 const SETUP_COMPLETED_FILE = path.join(PROJECT_SETTINGS_DIR, 'setup.json');
@@ -244,10 +250,69 @@ const DEFAULT_CONFIG = {
 
 // Environment variable support has been removed in favor of exclusive .i18ntk-config configuration
 
-let currentConfig = null;
-let configLoadInProgress = false;
-let recursionDepth = 0;
-const MAX_RECURSION_DEPTH = 15; // Increased to handle legitimate sequential calls
+let currentConfig = null;
+let configLoadInProgress = false;
+let recursionDepth = 0;
+const MAX_RECURSION_DEPTH = 15; // Increased to handle legitimate sequential calls
+let configSaveQueue = Promise.resolve();
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function acquireConfigLock(timeoutMs = CONFIG_LOCK_TIMEOUT_MS) {
+  const start = Date.now();
+  let lockHandle = null;
+
+  while (!lockHandle) {
+    try {
+      lockHandle = await fs.promises.open(CONFIG_LOCK_PATH, 'wx');
+      await lockHandle.writeFile(String(process.pid), 'utf8');
+      break;
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') {
+        throw error;
+      }
+
+      // Recover from stale lock files left by crashed processes.
+      try {
+        const stats = await fs.promises.stat(CONFIG_LOCK_PATH);
+        if (Date.now() - stats.mtimeMs > CONFIG_LOCK_STALE_MS) {
+          await fs.promises.unlink(CONFIG_LOCK_PATH);
+          continue;
+        }
+      } catch (_) {
+        // Lock may have been released between exists check and stat/unlink.
+      }
+
+      if (Date.now() - start >= timeoutMs) {
+        throw new Error(`Timed out waiting for config lock after ${timeoutMs}ms`);
+      }
+
+      await sleep(CONFIG_LOCK_RETRY_MS);
+    }
+  }
+
+  return async function releaseConfigLock() {
+    try {
+      if (lockHandle) {
+        await lockHandle.close();
+      }
+    } catch (_) {
+      // Best-effort close only.
+    }
+    try {
+      await fs.promises.unlink(CONFIG_LOCK_PATH);
+    } catch (_) {
+      // Best-effort cleanup only.
+    }
+  };
+}
+
+function isAutosaveDisabled() {
+  const flag = String(process.env.I18NTK_DISABLE_AUTOSAVE || '').trim().toLowerCase();
+  return flag === '1' || flag === 'true' || flag === 'yes';
+}
 
 function clone(obj) {
    return JSON.parse(JSON.stringify(obj));
@@ -424,28 +489,71 @@ function loadConfig() {
 
 async function saveConfig(cfg = currentConfig) {
   if (!cfg || typeof cfg !== 'object') return;
-
-  try {
-    // Ensure settings directory exists
-    if (!SecurityUtils.safeExistsSync(PROJECT_SETTINGS_DIR)) {
-      fs.mkdirSync(PROJECT_SETTINGS_DIR, { recursive: true });
-    }
-
-    const serialized = JSON.stringify(cfg, null, 2);
-    if (typeof serialized !== 'string' || serialized.length === 0) {
-      throw new Error('Cannot save empty configuration payload');
-    }
 
-    // Atomic write prevents partially-written/empty config files.
-    const tempPath = `${PROJECT_CONFIG_PATH}.tmp`;
-    await fs.promises.writeFile(tempPath, serialized, 'utf8');
-    await fs.promises.rename(tempPath, PROJECT_CONFIG_PATH);
+  // Runtime/server safety valve: allow disabling disk writes entirely.
+  if (isAutosaveDisabled()) {
     currentConfig = cfg;
-  } catch (error) {
-    console.error('[i18ntk] Error saving configuration:', error.message);
-    throw error;
-  }
-}
+    if (!autosaveDisabledWarned) {
+      autosaveDisabledWarned = true;
+      console.warn('[i18ntk] Autosave disabled by I18NTK_DISABLE_AUTOSAVE. Keeping configuration in memory only.');
+    }
+    return false;
+  }
+
+  configSaveQueue = configSaveQueue.then(async () => {
+    let tempPath = null;
+    let releaseLock = null;
+    try {
+      // Ensure settings directory exists before any lock/file operations.
+      await fs.promises.mkdir(PROJECT_SETTINGS_DIR, { recursive: true });
+
+      releaseLock = await acquireConfigLock();
+
+      const serialized = JSON.stringify(cfg, null, 2);
+      if (typeof serialized !== 'string' || serialized.length === 0) {
+        throw new Error('Cannot save empty configuration payload');
+      }
+
+      // Use a unique temp file to avoid concurrent writer races.
+      const nonce = `${process.pid}.${Date.now()}.${crypto.randomUUID()}`;
+      tempPath = `${PROJECT_CONFIG_PATH}.${nonce}.tmp`;
+      await fs.promises.writeFile(tempPath, serialized, 'utf8');
+
+      try {
+        await fs.promises.rename(tempPath, PROJECT_CONFIG_PATH);
+      } catch (renameError) {
+        // If destination dir disappeared between checks, recreate and retry once.
+        if (renameError && renameError.code === 'ENOENT') {
+          await fs.promises.mkdir(PROJECT_SETTINGS_DIR, { recursive: true });
+          await fs.promises.rename(tempPath, PROJECT_CONFIG_PATH);
+        } else {
+          throw renameError;
+        }
+      }
+
+      currentConfig = cfg;
+      return true;
+    } catch (error) {
+      console.error('[i18ntk] Error saving configuration:', error.message);
+      return false;
+    } finally {
+      if (releaseLock) {
+        await releaseLock();
+      }
+      if (tempPath) {
+        try {
+          if (SecurityUtils.safeExistsSync(tempPath, path.dirname(tempPath))) {
+            fs.unlinkSync(tempPath);
+          }
+        } catch (_) {
+          // Best-effort temp cleanup only.
+        }
+      }
+    }
+  });
+
+  return configSaveQueue;
+}
 
 function getConfig() {
     // Check for recursion
@@ -486,7 +594,9 @@ function getConfig() {
          throw new Error('Invalid legacy configuration JSON');
        }
        const migratedConfig = { ...DEFAULT_CONFIG, ...legacyConfig };
-       saveConfig(migratedConfig);
+       saveConfig(migratedConfig).catch((err) => {
+         console.warn('[i18ntk] Warning: failed to persist migrated configuration:', err.message);
+       });
        currentConfig = migratedConfig;
 
        // Clean up legacy config
@@ -504,7 +614,9 @@ function getConfig() {
 
      // Use package defaults for new installation
      console.log('📦 Initializing with default configuration...');
-     saveConfig(DEFAULT_CONFIG);
+     saveConfig(DEFAULT_CONFIG).catch((err) => {
+       console.warn('[i18ntk] Warning: failed to persist default configuration:', err.message);
+     });
      currentConfig = DEFAULT_CONFIG;
      return resolvePaths(DEFAULT_CONFIG);
 

package/utils/npm-version-warning.js

@@ -0,0 +1,142 @@
+const https = require('https');
+const { compareVersions } = require('./version-utils');
+
+const DEFAULT_TIMEOUT_MS = 1800;
+const NPM_REGISTRY_BASE = 'https://registry.npmjs.org';
+
+function isSemverLike(version) {
+  return typeof version === 'string' && /^\d+\.\d+\.\d+([-.][0-9A-Za-z.-]+)?$/.test(version.trim());
+}
+
+function fetchPackageMetadata(packageName, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const safePackageName = encodeURIComponent(packageName);
+  const requestUrl = `${NPM_REGISTRY_BASE}/${safePackageName}`;
+
+  return new Promise((resolve) => {
+    let settled = false;
+
+    const finish = (value) => {
+      if (!settled) {
+        settled = true;
+        resolve(value);
+      }
+    };
+
+    const req = https.get(
+      requestUrl,
+      {
+        timeout: timeoutMs,
+        headers: {
+          Accept: 'application/json',
+          'User-Agent': 'i18ntk-version-check'
+        }
+      },
+      (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          finish(null);
+          return;
+        }
+
+        let raw = '';
+        res.on('data', (chunk) => {
+          raw += chunk;
+        });
+        res.on('end', () => {
+          try {
+            finish(JSON.parse(raw));
+          } catch {
+            finish(null);
+          }
+        });
+      }
+    );
+
+    req.on('timeout', () => {
+      req.destroy();
+      finish(null);
+    });
+    req.on('error', () => finish(null));
+  });
+}
+
+function getOutdatedStatus(currentVersion, metadata) {
+  if (!isSemverLike(currentVersion) || !metadata || !metadata.versions) {
+    return null;
+  }
+
+  const distTags = metadata['dist-tags'] || {};
+  const taggedLatest = distTags.latest;
+  const allPublishedVersions = Object.keys(metadata.versions).filter(isSemverLike);
+
+  if (allPublishedVersions.length === 0) {
+    return null;
+  }
+
+  const latestVersion = isSemverLike(taggedLatest)
+    ? taggedLatest
+    : allPublishedVersions.sort(compareVersions).at(-1);
+
+  if (!latestVersion || !isSemverLike(latestVersion)) {
+    return null;
+  }
+
+  const currentMeta = metadata.versions[currentVersion] || null;
+  const isCurrentDeprecated = Boolean(currentMeta && currentMeta.deprecated);
+  const isOutdated = compareVersions(currentVersion, latestVersion) < 0;
+
+  const newerStableVersions = allPublishedVersions.filter((version) => (
+    compareVersions(version, currentVersion) > 0 &&
+    compareVersions(version, latestVersion) <= 0
+  ));
+
+  return {
+    latestVersion,
+    isOutdated,
+    isCurrentDeprecated,
+    newerStableCount: newerStableVersions.length
+  };
+}
+
+async function checkNpmOutdated({ packageName, currentVersion, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  const metadata = await fetchPackageMetadata(packageName, timeoutMs);
+  return getOutdatedStatus(currentVersion, metadata);
+}
+
+async function printUpgradeWarningIfOutdated({
+  packageName,
+  currentVersion,
+  timeoutMs = DEFAULT_TIMEOUT_MS
+}) {
+  if (process.env.I18NTK_DISABLE_UPDATE_CHECK === 'true') {
+    return;
+  }
+
+  const status = await checkNpmOutdated({ packageName, currentVersion, timeoutMs });
+  if (!status) {
+    return;
+  }
+
+  if (status.isCurrentDeprecated) {
+    console.warn(
+      `\n⚠️  Installed ${packageName}@${currentVersion} is deprecated on npm. ` +
+      `Upgrade to ${packageName}@${status.latestVersion}:\n` +
+      `   npm install -g ${packageName}@latest`
+    );
+    return;
+  }
+
+  if (status.isOutdated) {
+    const suffix = status.newerStableCount === 1 ? '' : 's';
+    console.warn(
+      `\n⚠️  Update available for ${packageName}: ${currentVersion} -> ${status.latestVersion} ` +
+      `(${status.newerStableCount} newer release${suffix}).\n` +
+      `   Run: npm install -g ${packageName}@latest`
+    );
+  }
+}
+
+module.exports = {
+  checkNpmOutdated,
+  printUpgradeWarningIfOutdated
+};