i18ntk 1.10.1 → 2.0.2

package/utils/env-manager.js

@@ -0,0 +1,256 @@
+/**
+ * Centralized Environment Variable Manager
+ * 
+ * This module provides secure access to a fixed allowlist of environment variables.
+ * Only explicitly defined environment variables are accessible, all others are ignored.
+ * No secrets or sensitive data should ever be stored in environment variables.
+ */
+
+const ALLOWED_ENV_VARS = {
+  // Logging and output
+  'I18NTK_LOG_LEVEL': {
+    default: 'error',
+    validate: (value) => ['error', 'warn', 'info', 'debug', 'silent'].includes(value.toLowerCase()),
+    transform: (value) => value.toLowerCase()
+  },
+  
+  'I18NTK_OUTDIR': {
+    default: './i18ntk-reports',
+    validate: (value) => typeof value === 'string' && value.length > 0,
+    transform: (value) => value.trim()
+  },
+  
+  // UI and interaction
+  'I18NTK_UI_LANGUAGE': {
+    default: 'en',
+    validate: (value) => ['en', 'de', 'es', 'fr', 'ru', 'ja', 'zh'].includes(value.toLowerCase()),
+    transform: (value) => value.toLowerCase()
+  },
+  
+  'I18NTK_SILENT': {
+    default: 'false',
+    validate: (value) => ['true', 'false', '1', '0', 'yes', 'no'].includes(value.toLowerCase()),
+    transform: (value) => {
+      const lower = value.toLowerCase();
+      return lower === 'true' || lower === '1' || lower === 'yes' ? 'true' : 'false';
+    }
+  },
+  
+  // Debug and development
+  'I18NTK_DEBUG_LOCALES': {
+    default: '0',
+    validate: (value) => ['0', '1', 'true', 'false'].includes(value.toLowerCase()),
+    transform: (value) => {
+      const lower = value.toLowerCase();
+      return lower === '1' || lower === 'true' ? '1' : '0';
+    }
+  },
+  
+  // Runtime configuration
+  'I18NTK_RUNTIME_DIR': {
+    default: null,
+    validate: (value) => typeof value === 'string',
+    transform: (value) => value.trim() || null
+  },
+  
+  'I18NTK_I18N_DIR': {
+    default: './locales',
+    validate: (value) => typeof value === 'string' && value.length > 0,
+    transform: (value) => value.trim()
+  },
+  
+  'I18NTK_SOURCE_DIR': {
+    default: './locales',
+    validate: (value) => typeof value === 'string' && value.length > 0,
+    transform: (value) => value.trim()
+  },
+  
+  'I18NTK_PROJECT_ROOT': {
+    default: '.',
+    validate: (value) => typeof value === 'string' && value.length > 0,
+    transform: (value) => value.trim()
+  },
+  
+  // Framework detection
+  'I18NTK_FRAMEWORK_PREFERENCE': {
+    default: 'auto',
+    validate: (value) => ['auto', 'vanilla', 'react', 'vue', 'angular', 'svelte', 'i18next', 'nuxt', 'next', 'django', 'flask', 'fastapi', 'spring-boot', 'laravel'].includes(value.toLowerCase()),
+    transform: (value) => value.toLowerCase()
+  },
+  
+  'I18NTK_FRAMEWORK_FALLBACK': {
+    default: 'vanilla',
+    validate: (value) => ['vanilla', 'react', 'vue', 'angular', 'svelte', 'i18next', 'nuxt', 'next', 'django', 'flask', 'fastapi', 'spring-boot', 'laravel'].includes(value.toLowerCase()),
+    transform: (value) => value.toLowerCase()
+  },
+  
+  'I18NTK_FRAMEWORK_DETECT': {
+    default: 'true',
+    validate: (value) => ['true', 'false', '1', '0', 'yes', 'no'].includes(value.toLowerCase()),
+    transform: (value) => {
+      const lower = value.toLowerCase();
+      return lower === 'true' || lower === '1' || lower === 'yes' ? 'true' : 'false';
+    }
+  }
+};
+
+// Security: Block access to sensitive environment variables
+const BLOCKED_PATTERNS = [
+  /^SECRET/i,
+  /^PASSWORD/i,
+  /^KEY/i,
+  /^TOKEN/i,
+  /^API_KEY/i,
+  /^PRIVATE/i,
+  /^AUTH/i,
+  /^CREDENTIAL/i,
+  /^AWS_/i,
+  /^GITHUB_/i,
+  /^NPM_/i,
+  /^NODE_/i,
+  /^PATH$/,
+  /^HOME$/,
+  /^USER$/,
+  /^USERNAME$/,
+  /^SHELL$/,
+  /^TERM$/,
+  /^DISPLAY$/,
+  /^LANG$/,
+  /^LC_/i
+];
+
+class EnvironmentManager {
+  constructor() {
+    this._cache = new Map();
+    this._validated = new Set();
+  }
+
+  /**
+   * Get a validated environment variable value
+   * @param {string} name - Environment variable name
+   * @returns {string|null} - Validated value or null if not allowed
+   */
+  get(name) {
+    // Only allow explicitly defined variables
+    if (!ALLOWED_ENV_VARS[name]) {
+      return null;
+    }
+
+    // Check cache first
+    if (this._cache.has(name)) {
+      return this._cache.get(name);
+    }
+
+    const definition = ALLOWED_ENV_VARS[name];
+    const rawValue = process.env[name];
+
+    // Use default if not set
+    if (rawValue === undefined || rawValue === null || rawValue === '') {
+      this._cache.set(name, definition.default);
+      return definition.default;
+    }
+
+    // Validate and transform
+    try {
+      const transformed = definition.transform(rawValue);
+      
+      if (!definition.validate(transformed)) {
+        console.warn(`[i18ntk] Invalid value for ${name}: "${rawValue}". Using default: ${definition.default}`);
+        this._cache.set(name, definition.default);
+        return definition.default;
+      }
+
+      this._cache.set(name, transformed);
+      this._validated.add(name);
+      return transformed;
+    } catch (error) {
+      console.warn(`[i18ntk] Error processing ${name}: ${error.message}. Using default: ${definition.default}`);
+      this._cache.set(name, definition.default);
+      return definition.default;
+    }
+  }
+
+  /**
+   * Check if an environment variable is allowed
+   * @param {string} name - Environment variable name
+   * @returns {boolean} - True if allowed
+   */
+  isAllowed(name) {
+    return !!ALLOWED_ENV_VARS[name];
+  }
+
+  /**
+   * Get all allowed environment variables with their current values
+   * @returns {Object} - Object with variable names as keys and values
+   */
+  getAll() {
+    const result = {};
+    for (const name of Object.keys(ALLOWED_ENV_VARS)) {
+      result[name] = this.get(name);
+    }
+    return result;
+  }
+
+  /**
+   * Get documentation for all allowed environment variables
+   * @returns {Array} - Array of documentation objects
+   */
+  getDocumentation() {
+    return Object.entries(ALLOWED_ENV_VARS).map(([name, definition]) => ({
+      name,
+      default: definition.default,
+      description: this._getDescription(name)
+    }));
+  }
+
+  /**
+   * Clear the cache (for testing)
+   */
+  clearCache() {
+    this._cache.clear();
+    this._validated.clear();
+  }
+
+  /**
+   * Check if a variable name matches blocked patterns
+   * @param {string} name - Variable name to check
+   * @returns {boolean} - True if blocked
+   */
+  isBlocked(name) {
+    return BLOCKED_PATTERNS.some(pattern => pattern.test(name));
+  }
+
+  /**
+   * Get human-readable description for an environment variable
+   * @param {string} name - Environment variable name
+   * @returns {string} - Description
+   */
+  _getDescription(name) {
+    const descriptions = {
+      'I18NTK_LOG_LEVEL': 'Logging level (error, warn, info, debug, silent)',
+      'I18NTK_OUTDIR': 'Output directory for reports and generated files',
+      'I18NTK_UI_LANGUAGE': 'UI language (en, de, es, fr, ru, ja, zh)',
+      'I18NTK_SILENT': 'Run in silent mode without interactive prompts',
+      'I18NTK_DEBUG_LOCALES': 'Enable debug logging for locale loading',
+      'I18NTK_RUNTIME_DIR': 'Custom runtime directory path',
+      'I18NTK_I18N_DIR': 'Directory containing i18n/locale files',
+      'I18NTK_SOURCE_DIR': 'Source directory for scanning',
+      'I18NTK_PROJECT_ROOT': 'Project root directory',
+      'I18NTK_FRAMEWORK_PREFERENCE': 'Preferred framework (auto, react, vue, etc.)',
+      'I18NTK_FRAMEWORK_FALLBACK': 'Fallback framework when auto-detection fails',
+      'I18NTK_FRAMEWORK_DETECT': 'Enable automatic framework detection'
+    };
+    
+    return descriptions[name] || 'Configuration option';
+  }
+}
+
+// Create singleton instance
+const envManager = new EnvironmentManager();
+
+module.exports = {
+  EnvironmentManager,
+  envManager,
+  ALLOWED_ENV_VARS,
+  BLOCKED_PATTERNS
+};

package/utils/framework-detector.js

@@ -1,6 +1,6 @@
-const fs = require('fs');
 const path = require('path');
 const { gte } = require('./version-utils');
+const SecurityUtils = require('./security');
 
 // Framework compatibility information
 const FRAMEWORK_COMPATIBILITY = {
@@ -38,9 +38,9 @@ const FRAMEWORKS = {
     configFilePatterns: [
       /i18n\.(js|ts)$/,
       /i18ntk\.config\.(js|ts)$/,
-      /\.i18nrc(\.(js|json))?$/
+      /\.i18nrc(\.(js|json))?$/,
     ],
-    setupGuide: 'https://github.com/vladnosiv/i18n-management-toolkit',
+    setupGuide: 'Refer to the official i18ntk documentation on GitHub for setup instructions.',
     priority: 100, // Higher priority to detect before other frameworks
     ignore: [
       'node_modules/**',
@@ -52,7 +52,7 @@ const FRAMEWORKS = {
       '**/*.test.{js,jsx,ts,tsx}'
     ]
   },
-  
+
   // Vue i18n has highest specificity due to its unique syntax
   'vue-i18n': {
     name: 'vue-i18n',
@@ -66,7 +66,7 @@ const FRAMEWORKS = {
     ],
     ignore: ['node_modules/**']
   },
-  
+
   // React i18next has medium specificity
   'react-i18next': {
     name: 'React i18next',
@@ -76,9 +76,9 @@ const FRAMEWORKS = {
     regex: /\b(?:useTranslation|withTranslation|Trans|I18n|i18n\.t|t\(?=\s*[`'"])/,
     configFile: 'i18n.js',
     configFilePatterns: [/i18n\.(js|ts)$/, /i18next\.config\.(js|ts)$/],
-    setupGuide: 'https://react.i18next.com/'
+    setupGuide: 'Refer to the official react-i18next documentation for setup instructions.'
   },
-  
+
   // Base i18next has lowest specificity
   'i18next': {
     name: 'i18next',
@@ -246,10 +246,10 @@ const FRAMEWORKS = {
       'test/tmp/**'
     ]
   },
-  go: {
-    name: 'go',
-    deps: ['golang.org/x/text/language', 'github.com/nicksnyder/go-i18n/v2/i18n'],
-    globs: ['**/*.go'],
+  go: {
+    name: 'go',
+    deps: ['go-i18n', 'x-text'],
+    globs: ['**/*.go'],
     patterns: [
       /i18n\.NewMessage\([^,]+,\s*["`]([^"`]+)["`]/g,
       /i18n\.NewLocalizer\([^)]+\)\.MustLocalize\([^,]+,\s*["`]([^"`]+)["`]/g,
@@ -277,11 +277,6 @@ const FRAMEWORKS = {
   }
 };
 
-/**
- * Detect the i18n framework being used in the project
- * @param {string} projectRoot - Path to the project root
- * @returns {Promise<Object>} Object containing framework info and detection confidence
- */
 /**
  * Detects the i18n framework being used in the project
  * @param {string} projectRoot - Path to the project root
@@ -294,23 +289,31 @@ async function detectFramework(projectRoot) {
 
   const packageJsonPath = path.join(projectRoot, 'package.json');
   const detectedFrameworks = [];
-  
+
   // Only proceed if package.json exists
-  if (!fs.existsSync(packageJsonPath)) {
+  if (!SecurityUtils.safeExistsSync(packageJsonPath, projectRoot)) {
     return null;
   }
 
   try {
     // Read and parse package.json
-    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
-    const deps = { 
-      ...(packageJson.dependencies || {}), 
+    const packageJsonContent = SecurityUtils.safeReadFileSync(packageJsonPath, projectRoot, 'utf8');
+    if (!packageJsonContent) {
+      return null;
+    }
+    const packageJson = SecurityUtils.safeParseJSON(packageJsonContent);
+    if (!packageJson) {
+      return null;
+    }
+
+    const deps = {
+      ...(packageJson.dependencies || {}),
       ...(packageJson.devDependencies || {}),
       ...(packageJson.peerDependencies || {})
     };
 
     // Sort frameworks by priority (highest first)
-    const sortedFrameworks = Object.entries(FRAMEWORKS).sort((a, b) => 
+    const sortedFrameworks = Object.entries(FRAMEWORKS).sort((a, b) =>
       (b[1].priority || 0) - (a[1].priority || 0)
     );
 
@@ -350,7 +353,7 @@ async function detectFramework(projectRoot) {
         // First sort by confidence
         const confidenceDiff = b.confidence - a.confidence;
         if (confidenceDiff !== 0) return confidenceDiff;
-        
+
         // If confidence is equal, sort by priority
         return (b.priority || 0) - (a.priority || 0);
       })[0];
@@ -363,4 +366,4 @@ async function detectFramework(projectRoot) {
   }
 }
 
-module.exports = { detectFramework, FRAMEWORKS };
+module.exports = { detectFramework, FRAMEWORKS };

package/utils/i18n-helper.js

@@ -2,11 +2,47 @@
 const path = require('path');
 const fs = require('fs');
 
+// Lazy load SecurityUtils to prevent circular dependencies
+let securityUtils;
+function getSecurityUtils() {
+  if (!securityUtils) {
+    try {
+      securityUtils = require('./security');
+    } catch (error) {
+      // Fallback: use basic fs operations if SecurityUtils is not available
+      return {
+        safeExistsSync: (path) => {
+          try {
+            return require('fs').existsSync(path);
+          } catch {
+            return false;
+          }
+        },
+        safeWriteFileSync: (path, data, encoding) => {
+          try {
+            return require('fs').writeFileSync(path, data, encoding);
+          } catch {
+            return null;
+          }
+        },
+        safeReadFileSync: (path, encoding) => {
+          try {
+            return require('fs').readFileSync(path, encoding);
+          } catch {
+            return null;
+          }
+        }
+      };
+    }
+  }
+  return securityUtils;
+}
+
 // Helper functions for OS-agnostic path handling
 function toPosix(p) { return String(p).replace(/\\/g, '/'); }
-function isBundledPath(p) { 
-  const s = toPosix(p); 
-  return s.includes('/node_modules/i18ntk/') || s.includes('/i18ntk/ui-locales/'); 
+function isBundledPath(p) {
+  const s = toPosix(p);
+  return s.includes('/node_modules/i18ntk/') || s.includes('/i18ntk/ui-locales/');
 }
 
 function safeRequireConfig() {
@@ -21,7 +57,8 @@ function stripBOMAndComments(s) {
 }
 
 function readJsonSafe(file) {
-  const raw = fs.readFileSync(file, 'utf8');
+  const SecurityUtils = getSecurityUtils();
+  const raw = SecurityUtils.safeReadFileSync(file, path.dirname(file), 'utf8');
   return JSON.parse(stripBOMAndComments(raw));
 }
 
@@ -43,7 +80,8 @@ function resolveLocalesDirs() {
       try {
         const normalized = path.normalize(path.resolve(dir.trim()));
 
-        if (fs.existsSync(normalized) && fs.statSync(normalized).isDirectory()) {
+        const SecurityUtils = getSecurityUtils();
+        if (SecurityUtils.safeExistsSync(normalized) && fs.statSync(normalized).isDirectory()) {
           dirs.push(normalized);
         }
       } catch {
@@ -54,7 +92,7 @@ function resolveLocalesDirs() {
 
   const pkgA = pkgUiLocalesDirViaThisFile();
   addDir(pkgA);
-  
+
   const pkgB = pkgUiLocalesDirViaResolve();
   if (pkgB && pkgB !== pkgA) {
     addDir(pkgB);
@@ -78,28 +116,33 @@ function candidatesForLang(dir, lang) {
 
 function findLocaleFilesAllDirs(lang) {
   const dirs = resolveLocalesDirs();
-  
+
   if (process.env.I18NTK_DEBUG_LOCALES === '1') {
     console.log('🔎 i18ntk locale search dirs:', dirs);
   }
-  
+
   const files = [];
   const errors = [];
-  
+
   for (const dir of dirs) {
     for (const candidate of candidatesForLang(dir, lang)) {
       try {
-        if (fs.existsSync(candidate)) {
+        const SecurityUtils = getSecurityUtils();
+        if (SecurityUtils.safeExistsSync(candidate)) {
           const stats = fs.statSync(candidate);
           if (stats.isFile() && stats.size > 0) {
             // Validate file is readable and parseable
             fs.accessSync(candidate, fs.constants.R_OK);
             // Quick JSON validation
-            const content = fs.readFileSync(candidate, 'utf8');
-            if (content.trim().startsWith('{') || content.trim().startsWith('[')) {
-              files.push(candidate);
+            const content = SecurityUtils.safeReadFileSync(candidate, path.dirname(candidate), 'utf8');
+            if (content) {
+              if (content.trim().startsWith('{') || content.trim().startsWith('[')) {
+                files.push(candidate);
+              } else {
+                errors.push({ file: candidate, error: 'Invalid JSON format' });
+              }
             } else {
-              errors.push({ file: candidate, error: 'Invalid JSON format' });
+              errors.push({ file: candidate, error: 'Empty or unreadable file' });
             }
           }
         }
@@ -108,11 +151,11 @@ function findLocaleFilesAllDirs(lang) {
       }
     }
   }
-  
+
   if (process.env.I18NTK_DEBUG_LOCALES === '1' && errors.length > 0) {
     console.warn(`⚠️ Locale resolution errors for ${lang}:`, errors);
   }
-  
+
   return files;
 }
 
@@ -121,34 +164,34 @@ let currentLanguage = 'en';
 let isInitialized = false;
 const missingWarned = new Set();
 
-function loadTranslations(language) {
-  const cfg = safeRequireConfig();
-  const settings = cfg?.getConfig?.() || {};
-  const configuredLanguage = settings.uiLanguage || settings.language || 'en';
-
-  // Prioritize settings file language over environment variable
-  const requested = (configuredLanguage || language || 'en').toString();
+function loadTranslations(language) {
+  const cfg = safeRequireConfig();
+  const settings = cfg?.getConfig?.() || {};
+  const configuredLanguage = settings.uiLanguage || settings.language;
+
+  // Prioritize CLI argument, then UI language, then language fallback
+  const requested = (language || configuredLanguage || 'en').toString();
   const short = requested.split('-')[0].toLowerCase();
   const tryOrder = [requested, short, 'en'];
 
   const loadErrors = [];
-  
+
   for (const lang of tryOrder) {
     const files = findLocaleFilesAllDirs(lang);
-    
+
     // Prioritize bundled locales over project ones
       const prioritizedFiles = files.sort((a, b) => Number(isBundledPath(b)) - Number(isBundledPath(a)));
-    
+
     for (const file of prioritizedFiles) {
       try {
         translations = readJsonSafe(file);
         currentLanguage = lang;
         isInitialized = true;
-        
+
         if (process.env.I18NTK_DEBUG_LOCALES === '1') {
           console.log(`🗂 Loaded UI locale → ${file} (${lang})`);
         }
-        
+
         // Validate translations object
         if (typeof translations === 'object' && translations !== null) {
           return translations;
@@ -199,11 +242,11 @@ function loadTranslations(language) {
   };
   currentLanguage = 'en';
   isInitialized = true;
-  
+
   if (loadErrors.length > 0) {
     console.warn(`⚠️ No valid UI locale files found. Using built-in English strings.`);
   }
-  
+
   return translations;
 }
 
@@ -219,7 +262,7 @@ function t(key, params = {}) {
     loadTranslations();
     isInitialized = true;
   }
-  
+
   // Split the key into parts (e.g., 'module.subkey' -> ['module', 'subkey'])
   const keyParts = key.split('.');
   let value = translations;
@@ -258,12 +301,12 @@ function t(key, params = {}) {
     }
     return key;
   }
-  
+
   // If we found a string, interpolate parameters
   if (typeof value === 'string') {
     return interpolateParams(value, params);
   }
-  
+
   // Return the key if the final value is not a string
   console.warn(`Translation key does not resolve to a string: ${key}`);
   return key;
@@ -309,12 +352,13 @@ function getAvailableLanguages() {
   const langs = new Set();
   for (const d of dirs) {
     try {
-      if (!fs.existsSync(d)) continue;
+      const SecurityUtils = getSecurityUtils();
+      if (!SecurityUtils.safeExistsSync(d)) continue;
       for (const f of fs.readdirSync(d)) {
         if (f.endsWith('.json')) langs.add(path.basename(f, '.json'));
       }
       for (const f of fs.readdirSync(d, { withFileTypes: true })) {
-        if (f.isDirectory() && fs.existsSync(path.join(d, f.name, `${f.name}.json`))) {
+        if (f.isDirectory() && SecurityUtils.safeExistsSync(path.join(d, f.name, `${f.name}.json`))) {
           langs.add(f.name);
         }
       }
@@ -347,11 +391,11 @@ function deepMerge(target, source) {
  * Refresh language from settings manager
  * This ensures translations stay in sync with settings changes
  */
-function refreshLanguageFromSettings() {
-  const cfg = safeRequireConfig();
-  const settings = cfg?.getConfig?.() || {};
-  const configuredLanguage = settings.language || settings.uiLanguage || 'en';
-  
+function refreshLanguageFromSettings() {
+  const cfg = safeRequireConfig();
+  const settings = cfg?.getConfig?.() || {};
+  const configuredLanguage = settings.uiLanguage || settings.language || 'en';
+
   if (configuredLanguage !== currentLanguage) {
     isInitialized = false;
     loadTranslations(configuredLanguage);
@@ -373,4 +417,4 @@ module.exports = {
   deepMerge,
   refreshTranslations,
   refreshLanguageFromSettings
-};
+};