i18ntk 2.3.1 → 2.3.2

package/README.md

@@ -1,4 +1,4 @@
-# i18ntk v2.3.1
+# i18ntk v2.3.2
 
 Zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, and translation completion.
 
@@ -9,12 +9,14 @@ 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.2)](https://socket.dev/npm/package/i18ntk/overview/2.3.2)
 
 ## 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.2` may contain known stability and security issues.
+They are considered unsupported for production use. Upgrade to `2.3.2` 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.
 
 ## What i18ntk Does
 
@@ -151,7 +153,7 @@ Example `.i18ntk-config`:
 
 ```json
 {
-  "version": "2.3.1",
+  "version": "2.3.2",
   "sourceDir": "./locales",
   "i18nDir": "./locales",
   "outputDir": "./i18ntk-reports",
@@ -174,7 +176,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.2](docs/migration-guide-v2.3.2.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.2",
   "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.2",
     "releaseDate": "12/04/2026",
     "lastUpdated": "12/04/2026",
     "maintainer": "Vlad Noskov",
@@ -238,7 +238,8 @@
       "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.2 versions.",
+      "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 +265,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.2 may be unstable or insecure. Upgrade to 2.3.2 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/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
+};