i18ntk 2.3.7 → 2.3.8

package/README.md

@@ -1,4 +1,4 @@
-# i18ntk v2.3.7
+# i18ntk v2.3.8
 
 Zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, and translation completion.
 
@@ -9,12 +9,12 @@ 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.7)](https://socket.dev/npm/package/i18ntk/overview/2.3.7)
+[![socket](https://socket.dev/api/badge/npm/package/i18ntk/2.3.8)](https://socket.dev/npm/package/i18ntk/overview/2.3.8)
 
 ## Upgrade Notice
 
-Versions earlier than `2.3.7` may contain known stability and security issues.
-They are considered unsupported for production use. Upgrade to `2.3.7` or newer.
+Versions earlier than `2.3.8` may contain known stability and security issues.
+They are considered unsupported for production use. Upgrade to `2.3.8` or newer.
 
 ## What i18ntk Does
 
@@ -151,7 +151,7 @@ Example `.i18ntk-config`:
 
 ```json
 {
-  "version": "2.3.6",
+  "version": "2.3.8",
   "sourceDir": "./locales",
   "i18nDir": "./locales",
   "outputDir": "./i18ntk-reports",
@@ -174,7 +174,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.5](docs/migration-guide-v2.3.6.md)
+- [Migration Guide v2.3.8](docs/migration-guide-v2.3.8.md)
 - [Optimization Prompt](docs/development/package-optimization-prompt.md)
 
 ## Code of Conduct

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18ntk",
-  "version": "2.3.7",
+  "version": "2.3.8",
   "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",
@@ -213,7 +213,7 @@
     "languages:select": "node settings/settings-cli.js",
     "languages:list": "node settings/settings-cli.js --list-languages",
     "languages:status": "node settings/settings-cli.js --language-status",
-    "lint:locales": "node scripts/lint-locales.js" 
+    "lint:locales": "node scripts/lint-locales.js"
   },
   "engines": {
     "node": ">=16.0.0",
@@ -224,14 +224,17 @@
   },
   "preferGlobal": true,
   "versionInfo": {
-    "version": "2.3.7",
-    "releaseDate": "12/04/2026",
-    "lastUpdated": "12/04/2026",
+    "version": "2.3.8",
+    "releaseDate": "13/04/2026",
+    "lastUpdated": "13/04/2026",
     "maintainer": "Vlad Noskov",
     "changelog": "./CHANGELOG.md",
     "documentation": "./README.md",
     "apiReference": "./docs/api/API_REFERENCE.md",
     "majorChanges": [
+      "LOGGING: Introduced centralized structured logger with silent-by-default production behavior and DEBUG_MODE/JSON_LOG toggles.",
+      "SECURITY: Added internal path whitelist detection to prevent false-positive traversal warnings for package/project internals.",
+      "I18N: Added missing-key warning TTL cache to eliminate repeated translation-key spam during builds.",
       "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.",
@@ -265,7 +268,7 @@
       "spring-boot": ">=2.5.0",
       "laravel": ">=8.0.0"
     },
-    "supportPolicy": "Versions earlier than 2.3.7 may be unstable or insecure. Upgrade to 2.3.6 or newer."
+    "supportPolicy": "Versions earlier than 2.3.8 may be unstable or insecure. Upgrade to 2.3.8 or newer."
   },
   "_comment": "This package is zero-dependency and uses only native Node.js modules"
 }

package/utils/config-manager.js

@@ -1,8 +1,9 @@
 const fs = require('fs');
 const path = require('path');
-const os = require('os');
-const crypto = require('crypto');
-const SecurityUtils = require('./security');
+const os = require('os');
+const crypto = require('crypto');
+const SecurityUtils = require('./security');
+const { logger } = require('./logger');
 
 // Determine package directory and user project root
 const packageDir = path.resolve(__dirname, '..');
@@ -19,7 +20,55 @@ 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;
+let autosaveDisabledWarned = false;
+let defaultConfigNoticeShown = false;
+let configFallbackNoticeShown = false;
+
+function logInfo(message, details) {
+  logger.info(message, details);
+}
+
+function logWarn(message, details) {
+  logger.warn(message, details);
+}
+
+function logError(message, details) {
+  logger.error(message, details);
+}
+
+function notifyDefaultConfig(reason, error) {
+  if (defaultConfigNoticeShown) {
+    return;
+  }
+  defaultConfigNoticeShown = true;
+
+  logger.info('Using default configuration (reason: configuration error)', { reason });
+  if (logger.isDebugMode() && error) {
+    logger.debug(`Default configuration reason details: ${error.message}`, {
+      stack: error.stack
+    });
+  }
+}
+
+function notifyConfigFallback(error) {
+  if (!configFallbackNoticeShown) {
+    configFallbackNoticeShown = true;
+    logger.info('Using default configuration (reason: configuration error)', {
+      reason: 'configuration error'
+    });
+  }
+
+  logger.recordFirstError('config:load-fallback', {
+    message: error && error.message ? error.message : 'Unknown configuration error',
+    stack: error && error.stack ? error.stack : null
+  });
+
+  if (logger.isDebugMode() && error) {
+    logger.debug(`Configuration load fallback details: ${error.message}`, {
+      stack: error.stack
+    });
+  }
+}
 
 // Setup tracking file
 const SETUP_COMPLETED_FILE = path.join(PROJECT_SETTINGS_DIR, 'setup.json');
@@ -381,7 +430,7 @@ function tryReadJson(filePath) {
 
     const data = SecurityUtils.safeReadFileSync(filePath, path.dirname(filePath), 'utf8');
     if (!data || data.trim() === '') {
-      console.warn(`[i18ntk] Warning: Empty or invalid JSON file at ${filePath}`);
+      logWarn(`[i18ntk] Warning: Empty or invalid JSON file at ${filePath}`);
       return null;
     }
 
@@ -390,18 +439,18 @@ function tryReadJson(filePath) {
       return parsed;
     }
 
-    console.error(`[i18ntk] Error parsing JSON from ${filePath}: Invalid JSON content`);
+    logError(`[i18ntk] Error parsing JSON from ${filePath}: Invalid JSON content`);
     // Create a backup of the corrupted file
     const backupPath = `${filePath}.corrupted-${Date.now()}.bak`;
     try {
       SecurityUtils.safeWriteFileSync(backupPath, data, path.dirname(backupPath), 'utf8');
-      console.warn(`[i18ntk] Created backup of corrupted config at ${backupPath}`);
+      logWarn(`[i18ntk] Created backup of corrupted config at ${backupPath}`);
     } catch (backupError) {
-      console.error(`[i18ntk] Failed to create backup of corrupted config: ${backupError.message}`);
+      logError(`[i18ntk] Failed to create backup of corrupted config: ${backupError.message}`);
     }
     return null;
   } catch (error) {
-    console.error(`[i18ntk] Error reading config file at ${filePath}: ${error.message}`);
+    logError(`[i18ntk] Error reading config file at ${filePath}: ${error.message}`);
     return null;
   }
 }
@@ -420,11 +469,11 @@ async function migrateLegacyIfNeeded(baseCfg) {
         // Best-effort removal of legacy file to prevent future use
         try { fs.unlinkSync(LEGACY_CONFIG_PATH); } catch (_) {}
         // Deprecation notice
-        console.warn('[i18ntk] Deprecated config location detected (~/.i18ntk). Configuration was migrated to project .i18ntk-config.');
+        logWarn('[i18ntk] Deprecated config location detected (~/.i18ntk). Configuration was migrated to project .i18ntk-config.');
         return merged;
       } catch (_) {
         // If write fails, fall back to in-memory config without deleting legacy
-        console.warn('[i18ntk] Deprecated config location detected (~/.i18ntk). Using migrated settings in memory; failed to persist to .i18ntk-config.');
+        logWarn('[i18ntk] Deprecated config location detected (~/.i18ntk). Using migrated settings in memory; failed to persist to .i18ntk-config.');
         return merged;
       }
     }
@@ -445,7 +494,7 @@ function loadConfig() {
 
     // Prevent concurrent loading
     if (configLoadInProgress) {
-      console.warn('[i18ntk] Configuration loading already in progress, returning defaults');
+      logWarn('[i18ntk] Configuration loading already in progress, returning defaults');
       resetRecursionGuard();
       return clone(DEFAULT_CONFIG);
     }
@@ -472,7 +521,7 @@ function loadConfig() {
          // Attempt to migrate to project settings
          // Ignore migration errors; we still return merged cfg in memory
          // eslint-disable-next-line no-unused-vars
-         console.warn('[i18ntk] Detected legacy config at ~/.i18ntk. Migrating to project settings directory...');
+         logWarn('[i18ntk] Detected legacy config at ~/.i18ntk. Migrating to project settings directory...');
          const _ = (async () => { await migrateLegacyIfNeeded(DEFAULT_CONFIG); })();
        }
      }
@@ -481,7 +530,8 @@ function loadConfig() {
      currentConfig = cfg;
      return currentConfig;
    } catch (error) {
-     console.error('[i18ntk] Error in loadConfig:', error.message);
+     logError('[i18ntk] Error in loadConfig', { error: error.message });
+     notifyConfigFallback(error);
      currentConfig = clone(DEFAULT_CONFIG);
      return currentConfig;
    } finally {
@@ -498,7 +548,7 @@ async function saveConfig(cfg = currentConfig) {
     currentConfig = cfg;
     if (!autosaveDisabledWarned) {
       autosaveDisabledWarned = true;
-      console.warn('[i18ntk] Autosave disabled by I18NTK_DISABLE_AUTOSAVE. Keeping configuration in memory only.');
+      logWarn('[i18ntk] Autosave disabled by I18NTK_DISABLE_AUTOSAVE. Keeping configuration in memory only.');
     }
     return false;
   }
@@ -540,7 +590,7 @@ async function saveConfig(cfg = currentConfig) {
       currentConfig = cfg;
       return true;
     } catch (error) {
-      console.error('[i18ntk] Error saving configuration:', error.message);
+      logError('[i18ntk] Error saving configuration', { error: error.message });
       return false;
     } finally {
       if (releaseLock) {
@@ -593,7 +643,7 @@ function getConfig() {
 
      // Check for legacy config for migration
      if (SecurityUtils.safeExistsSync(LEGACY_CONFIG_PATH)) {
-       console.log('📦 Migrating legacy configuration...');
+       logInfo('Migrating legacy configuration');
        const legacyRaw = SecurityUtils.safeReadFileSync(LEGACY_CONFIG_PATH, path.dirname(LEGACY_CONFIG_PATH), 'utf8');
        const legacyConfig = SecurityUtils.safeParseJSON(legacyRaw);
        if (!legacyConfig || typeof legacyConfig !== 'object') {
@@ -601,7 +651,7 @@ function getConfig() {
        }
        const migratedConfig = { ...DEFAULT_CONFIG, ...legacyConfig };
        saveConfig(migratedConfig).catch((err) => {
-         console.warn('[i18ntk] Warning: failed to persist migrated configuration:', err.message);
+         logWarn('[i18ntk] Warning: failed to persist migrated configuration', { error: err.message });
        });
        currentConfig = migratedConfig;
 
@@ -619,18 +669,18 @@ function getConfig() {
      }
 
      // Use package defaults for new installation
-     console.log('📦 Initializing with default configuration...');
-     saveConfig(DEFAULT_CONFIG).catch((err) => {
-       console.warn('[i18ntk] Warning: failed to persist default configuration:', err.message);
-     });
-     currentConfig = DEFAULT_CONFIG;
-     return resolvePaths(DEFAULT_CONFIG);
-
-   } catch (error) {
-     console.warn('⚠️  Error loading configuration, using defaults:', error.message);
-     currentConfig = DEFAULT_CONFIG;
-     return resolvePaths(DEFAULT_CONFIG);
-   }
+     notifyDefaultConfig('default initialization');
+     saveConfig(DEFAULT_CONFIG).catch((err) => {
+       logWarn('[i18ntk] Warning: failed to persist default configuration', { error: err.message });
+     });
+     currentConfig = DEFAULT_CONFIG;
+     return resolvePaths(DEFAULT_CONFIG);
+
+   } catch (error) {
+     notifyConfigFallback(error);
+     currentConfig = DEFAULT_CONFIG;
+     return resolvePaths(DEFAULT_CONFIG);
+   }
 }
 
 async function setConfig(cfg) {
@@ -693,3 +743,7 @@ module.exports = {
   toRelative,
   normalizePathValue,
 }
+
+
+
+

package/utils/config.js

@@ -1,6 +1,7 @@
-const fs = require('fs');
-const path = require('path');
-const SecurityUtils = require('./security');
+const fs = require('fs');
+const path = require('path');
+const SecurityUtils = require('./security');
+const { logger } = require('./logger');
 
 const settingsManager = require('../settings/settings-manager');
 const CONFIG_FILE = 'i18ntk-config.json';
@@ -66,11 +67,11 @@ function loadConfig(cwd = settingsManager.configDir) {
     }
     
     throw new Error('Invalid configuration format');
-  } catch (error) {
-    console.error(`Error loading config: ${error.message}`);
-    return null;
-  }
-}
+  } catch (error) {
+    logger.debug(`Error loading config: ${error.message}`, { stack: error.stack });
+    return null;
+  }
+}
 
 /**
  * Saves configuration to file
@@ -96,11 +97,11 @@ function saveConfig(config, cwd = settingsManager.configDir) {
     );
     
     return true;
-  } catch (error) {
-    console.error(`Error saving config: ${error.message}`);
-    return false;
-  }
-}
+  } catch (error) {
+    logger.error(`Error saving config: ${error.message}`);
+    return false;
+  }
+}
 
 /**
  * Ensures default values for configuration
@@ -127,4 +128,4 @@ module.exports = {
   saveConfig, 
   ensureConfigDefaults,
   validatePath // Exported for testing
-};
+};

package/utils/i18n-helper.js

@@ -1,6 +1,7 @@
 // utils/i18n-helper.js
-const path = require('path');
-const fs = require('fs');
+const path = require('path');
+const fs = require('fs');
+const { logger } = require('./logger');
 
 // Lazy load SecurityUtils to prevent circular dependencies
 let securityUtils;
@@ -200,10 +201,21 @@ function findLocaleFilesAllDirs(lang, preferredDir) {
   return files;
 }
 
-let translations = {};
-let currentLanguage = 'en';
-let isInitialized = false;
-const missingWarned = new Set();
+let translations = {};
+let currentLanguage = 'en';
+let isInitialized = false;
+const missingKeyCache = new Map();
+const missingKeyTtlMs = 5 * 60 * 1000;
+
+function shouldReportMissingKey(key) {
+  const now = Date.now();
+  const expiresAt = missingKeyCache.get(key) || 0;
+  if (expiresAt > now) {
+    return false;
+  }
+  missingKeyCache.set(key, now + missingKeyTtlMs);
+  return true;
+}
 
 function loadTranslations(language) {
   const cfg = safeRequireConfig();
@@ -286,9 +298,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.`);
-  }
+  if (loadErrors.length > 0) {
+    logger.warn('No valid UI locale files found. Using built-in English strings.', {
+      errorCount: loadErrors.length
+    });
+  }
 
   return translations;
 }
@@ -337,23 +351,24 @@ function t(key, params = {}) {
     }
   }
 
-  if (typeof value === 'undefined') {
-    if (!missingWarned.has(key)) {
-      missingWarned.add(key);
-      console.warn(`Translation key not found: ${key}`);
-    }
-    return key;
-  }
+  if (typeof value === 'undefined') {
+    if (shouldReportMissingKey(key)) {
+      logger.logMissingTranslationKey(key, 'Configuration error');
+    }
+    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;
-}
+  // Return the key if the final value is not a string
+  if (shouldReportMissingKey(`${key}:non-string`)) {
+    logger.warn(`Translation key does not resolve to a string: ${key}`);
+  }
+  return key;
+}
 
 /**
  * Interpolate parameters into a translation string

package/utils/logger.js

@@ -1,64 +1,233 @@
-const colors = require('./colors-new');
-const { envManager } = require('./env-manager');
-
-// Enhanced logger with TTY detection and proper stream handling
-const logger = {
-  // Basic log function with color support
-  log: (message, color = '') => {
-    const output = color ? color(message) : message;
-    if (process.stdout.isTTY) {
-      process.stdout.write(output + '\n');
-    } else {
-      console.log(output);
-    }
-  },
-  
-  // Error logging (goes to stderr)
-  error: (message) => {
-    const output = `❌ ${message}`;
-    if (process.stderr.isTTY) {
-      process.stderr.write(colors.bright(colors.red(output)) + '\n');
-    } else {
-      console.error(output);
-    }
-  },
-  
-  // Success logging
-  success: (message) => {
-    const output = `✅ ${message}`;
-    logger.log(output, colors.green);
-  },
-  
-  // Warning logging (goes to stderr)
-  warn: (message) => {
-    const output = `⚠️  ${message}`;
-    if (process.stderr.isTTY) {
-      process.stderr.write(colors.bright(colors.yellow(output)) + '\n');
-    } else {
-      console.warn(output);
-    }
-  },
-  
-  // Info logging
-  info: (message) => {
-    const output = `ℹ️  ${message}`;
-    logger.log(output, colors.blue);
-  },
-  
-  // Debug logging (only when DEBUG env var is set or log level is debug)
-  debug: (message) => {
-    const logLevel = envManager.get('I18NTK_LOG_LEVEL');
-    const debugEnabled = logLevel === 'debug';
-    
-    if (debugEnabled) {
-      const output = `[DEBUG] ${message}`;
-      if (process.stderr.isTTY) {
-        process.stderr.write(colors.gray(output) + '\n');
-      } else {
-        console.debug(output);
-      }
-    }
-  }
-};
-
-module.exports = { colors, logger };
+const colors = require('./colors-new');
+
+const LEVELS = { error: 0, warn: 1, info: 2, debug: 3 };
+const DEFAULT_INTERNAL_PREFIXES = ['[BUILD]', '[WORKERS]', '[I18N]', '[SECURITY]', '[SUCCESS]', '[WARN]', '[ERROR]', '[INFO]', '[DEBUG]'];
+const FIRST_ERROR_CONTEXT = new Map();
+
+function asBoolean(value) {
+  return String(value || '').trim().toLowerCase() === 'true';
+}
+
+function resolveLevel() {
+  const debugMode = asBoolean(process.env.DEBUG_MODE);
+  const configured = String(process.env.I18NTK_LOG_LEVEL || '').trim().toLowerCase();
+  if (configured && Object.prototype.hasOwnProperty.call(LEVELS, configured)) {
+    return configured;
+  }
+
+  if (debugMode) {
+    return 'debug';
+  }
+
+  // Silent-by-default in production-like builds.
+  if (process.env.NODE_ENV === 'production' || asBoolean(process.env.CI)) {
+    return 'error';
+  }
+
+  return 'warn';
+}
+
+function shouldLog(level) {
+  const active = resolveLevel();
+  return LEVELS[level] <= LEVELS[active];
+}
+
+function normalizePrefix(prefix, fallback) {
+  const value = String(prefix || fallback || '[INFO]').trim();
+  if (/^\[[^\]]+\]$/.test(value)) {
+    return value;
+  }
+  return `[${value.replace(/^[\[]|[\]]$/g, '').toUpperCase()}]`;
+}
+
+function write(level, message, options = {}) {
+  if (!shouldLog(level)) return;
+
+  const jsonMode = asBoolean(process.env.JSON_LOG);
+  const prefix = normalizePrefix(options.prefix, `[${level.toUpperCase()}]`);
+  const details = options.details && typeof options.details === 'object' ? options.details : undefined;
+  const text = String(message || '').trim();
+
+  if (jsonMode) {
+    const payload = {
+      timestamp: new Date().toISOString(),
+      level,
+      prefix,
+      message: text,
+      ...(details ? { details } : {})
+    };
+    const line = JSON.stringify(payload);
+    if (level === 'error' || level === 'warn') {
+      process.stderr.write(`${line}\n`);
+    } else {
+      process.stdout.write(`${line}\n`);
+    }
+    return;
+  }
+
+  const line = `${prefix}  ${text}`;
+  if (level === 'error') {
+    process.stderr.write(`${colors.red(line)}\n`);
+    return;
+  }
+  if (level === 'warn') {
+    process.stderr.write(`${colors.yellow(line)}\n`);
+    return;
+  }
+  if (level === 'debug') {
+    process.stdout.write(`${colors.gray(line)}\n`);
+    return;
+  }
+
+  process.stdout.write(`${line}\n`);
+}
+
+function formatDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return 'instant';
+  if (ms < 50) return 'instant';
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  const minutes = Math.floor(ms / 60000);
+  const seconds = Math.round((ms % 60000) / 1000);
+  return `${minutes}m${seconds}s`;
+}
+
+function recordFirstError(key, context) {
+  if (!key || FIRST_ERROR_CONTEXT.has(key)) {
+    return;
+  }
+
+  FIRST_ERROR_CONTEXT.set(key, {
+    timestamp: new Date().toISOString(),
+    ...context
+  });
+}
+
+function getFirstErrorContext(key) {
+  return FIRST_ERROR_CONTEXT.get(key) || null;
+}
+
+function flushErrorContexts() {
+  const entries = Array.from(FIRST_ERROR_CONTEXT.entries()).map(([key, value]) => ({ key, ...value }));
+  FIRST_ERROR_CONTEXT.clear();
+  return entries;
+}
+
+function emitErrorContextSummary({ force = false } = {}) {
+  const contexts = Array.from(FIRST_ERROR_CONTEXT.entries());
+  if (!contexts.length) return;
+  if (!force && !asBoolean(process.env.DEBUG_MODE)) return;
+
+  for (const [key, context] of contexts) {
+    write('debug', `First error context (${key})`, { prefix: '[ERROR]', details: context });
+  }
+}
+
+function logMissingTranslationKey(key, fallback = 'Configuration error') {
+  write('warn', `Missing key: ${key} (fallback: '${fallback}')`, { prefix: '[I18N]' });
+}
+
+function createBuildProgressReporter(totalPages) {
+  const safeTotal = Math.max(1, Number(totalPages) || 1);
+  let lastBucket = 0;
+
+  return {
+    update(completedPages) {
+      const completed = Math.max(0, Math.min(safeTotal, Number(completedPages) || 0));
+      const percent = Math.floor((completed / safeTotal) * 100);
+      const bucket = Math.floor(percent / 10) * 10;
+      if (bucket <= lastBucket || bucket === 0) return;
+      lastBucket = bucket;
+
+      const pct = `${String(bucket).padStart(3, ' ')}%`;
+      write('info', `${pct} (${completed}/${safeTotal} pages)`, { prefix: '[BUILD]' });
+    }
+  };
+}
+
+function buildSuccessSummary({ durationMs, pages, warnings = 0 }) {
+  const duration = formatDuration(durationMs);
+  write('info', `Build completed in ${duration} (${pages} pages, ${warnings} warnings)`, { prefix: '[SUCCESS]' });
+}
+
+function createWorkerPoolMonitor(activeWorkers = 0) {
+  const startedAt = Date.now();
+  let tasks = 0;
+  let totalTaskDurationMs = 0;
+  let workers = Math.max(0, Number(activeWorkers) || 0);
+
+  return {
+    setActive(count) {
+      workers = Math.max(0, Number(count) || 0);
+    },
+    recordTask(durationMs) {
+      tasks += 1;
+      totalTaskDurationMs += Math.max(0, Number(durationMs) || 0);
+    },
+    report() {
+      const avg = tasks > 0 ? (totalTaskDurationMs / tasks) / 1000 : 0;
+      write('info', `${workers} active (avg ${avg.toFixed(1)}s/task)`, { prefix: '[WORKERS]' });
+      return {
+        workers,
+        tasks,
+        avgSecondsPerTask: Number(avg.toFixed(2)),
+        elapsed: formatDuration(Date.now() - startedAt)
+      };
+    }
+  };
+}
+
+const logger = {
+  log(message, color = null) {
+    const output = typeof color === 'function' ? color(String(message)) : String(message);
+    write('info', output, { prefix: '[INFO]' });
+  },
+  info(message, details) {
+    write('info', String(message), { prefix: '[INFO]', details });
+  },
+  warn(message, details) {
+    write('warn', String(message), { prefix: '[WARN]', details });
+  },
+  error(message, details) {
+    write('error', String(message), { prefix: '[ERROR]', details });
+  },
+  debug(message, details) {
+    write('debug', String(message), { prefix: '[DEBUG]', details });
+  },
+  success(message, details) {
+    write('info', String(message), { prefix: '[SUCCESS]', details });
+  },
+  security(level, message, details) {
+    write(level, String(message), { prefix: '[SECURITY]', details });
+  },
+  build(message, details) {
+    write('info', String(message), { prefix: '[BUILD]', details });
+  },
+  isDebugMode() {
+    return asBoolean(process.env.DEBUG_MODE) || resolveLevel() === 'debug';
+  },
+  shouldLog,
+  formatDuration,
+  recordFirstError,
+  getFirstErrorContext,
+  flushErrorContexts,
+  emitErrorContextSummary,
+  buildSuccessSummary,
+  logMissingTranslationKey,
+  createBuildProgressReporter,
+  createWorkerPoolMonitor,
+  // Keep compatibility for callers that rely on known prefixes.
+  KNOWN_PREFIXES: DEFAULT_INTERNAL_PREFIXES
+};
+
+module.exports = {
+  colors,
+  logger,
+  formatDuration,
+  createBuildProgressReporter,
+  createWorkerPoolMonitor,
+  recordFirstError,
+  getFirstErrorContext,
+  flushErrorContexts,
+  emitErrorContextSummary
+};

package/utils/security.js

@@ -1,26 +1,93 @@
-const path = require('path');
-const fs = require('fs');
-const crypto = require('crypto');
-
-
-// Lazy load configManager to avoid circular dependency
-let configManager;
-let configManagerLoadAttempted = false;
-function getConfigManager() {
-  if (!configManager && !configManagerLoadAttempted) {
-    configManagerLoadAttempted = true;
-    try {
-      configManager = require('./config-manager');
-    } catch (error) {
-      // Return null if config-manager can't be loaded
-      return null;
-    }
-  }
-  return configManager;
-}
-
-// Lazy load i18n to prevent initialization race conditions
-let i18n;
+const path = require('path');
+const fs = require('fs');
+const crypto = require('crypto');
+const { logger } = require('./logger');
+
+const INTERNAL_MANIFEST_CACHE = {
+  initialized: false,
+  roots: new Set()
+};
+
+function findPackageRoot(startDir) {
+  let current = path.resolve(startDir || process.cwd());
+  while (true) {
+    const manifest = path.join(current, 'package.json');
+    if (fs.existsSync(manifest)) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+function initializeInternalRoots() {
+  if (INTERNAL_MANIFEST_CACHE.initialized) {
+    return INTERNAL_MANIFEST_CACHE.roots;
+  }
+
+  INTERNAL_MANIFEST_CACHE.initialized = true;
+  const roots = INTERNAL_MANIFEST_CACHE.roots;
+  const candidates = [
+    process.cwd(),
+    path.resolve(__dirname, '..'),
+    findPackageRoot(process.cwd()),
+    findPackageRoot(path.resolve(__dirname, '..'))
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    roots.add(path.resolve(candidate));
+  }
+
+  const custom = String(process.env.I18NTK_INTERNAL_PATH_PREFIXES || '')
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  for (const prefix of custom) {
+    roots.add(path.resolve(prefix));
+  }
+
+  return roots;
+}
+
+function normalizeForCompare(value) {
+  return String(value || '').replace(/\\/g, '/').toLowerCase();
+}
+
+function isPathInside(root, target) {
+  const normalizedRoot = normalizeForCompare(path.resolve(root));
+  const normalizedTarget = normalizeForCompare(path.resolve(target));
+  return normalizedTarget === normalizedRoot || normalizedTarget.startsWith(`${normalizedRoot}/`);
+}
+
+function isInternalPath(inputPath) {
+  if (!inputPath || typeof inputPath !== 'string') {
+    return false;
+  }
+  const roots = initializeInternalRoots();
+  const absolute = path.resolve(inputPath);
+  for (const root of roots) {
+    if (isPathInside(root, absolute)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function detectDangerReason(filePath) {
+  if (/\.\.(\/|\\|$)/.test(filePath)) return 'Contains parent directory traversal segments';
+  if (/(^|[\/\\])~([\/\\]|$)/.test(filePath)) return 'Contains home-directory shorthand';
+  if (/\$\{/.test(filePath)) return 'Contains variable expansion token';
+  if (/`/.test(filePath)) return 'Contains command substitution token';
+  if (/[|;&<>]/.test(filePath)) return 'Contains shell metacharacters';
+  return null;
+}
+
+
+// Lazy load i18n to prevent initialization race conditions
+let i18n;
 function getI18n() {
   if (!i18n) {
     try {
@@ -74,11 +141,13 @@ static _logging = false;
       SecurityUtils._operationStack = new Set();
     }
 
-    if (SecurityUtils._operationStack.has(operationName)) {
-      const i18n = getI18n();
-      SecurityUtils.logSecurityEvent(i18n.t('security.recursion_detected', { operation: operationName }), 'error');
-      return null;
-    }
+    if (SecurityUtils._operationStack.has(operationName)) {
+      SecurityUtils.logSecurityEvent('Recursion detected while performing secure operation', 'warn', {
+        operation: operationName,
+        source: 'internal'
+      });
+      return null;
+    }
 
     SecurityUtils._operationStack.add(operationName);
 
@@ -88,12 +157,15 @@ static _logging = false;
       let hasResult = false;
       let timeoutId = null;
 
-      timeoutId = setTimeout(() => {
-        if (!hasResult) {
-          const i18n = getI18n();
-          SecurityUtils.logSecurityEvent(i18n.t('security.operation_timeout', { operation: operationName }), 'warning');
-        }
-      }, timeoutMs);
+      timeoutId = setTimeout(() => {
+        if (!hasResult) {
+          SecurityUtils.logSecurityEvent('Secure operation timeout', 'warn', {
+            operation: operationName,
+            timeoutMs,
+            source: 'internal'
+          });
+        }
+      }, timeoutMs);
 
       // Execute operation synchronously
       result = operation();
@@ -105,12 +177,12 @@ static _logging = false;
 
       return result;
     } catch (error) {
-    const i18n = getI18n();
-    SecurityUtils.logSecurityEvent('Operation error', 'error', {
-    operation: operationName,
-    error: error.message
-    });
-    return null;
+      SecurityUtils.logSecurityEvent('Secure operation error', 'error', {
+        operation: operationName,
+        error: error.message,
+        source: 'internal'
+      });
+      return null;
     } finally {
       SecurityUtils._operationStack.delete(operationName);
     }
@@ -122,60 +194,40 @@ static _logging = false;
    * @param {string} level - Log level (info, warn, error)
    * @param {object} details - Additional details
    */
-  static logSecurityEvent(event, level = 'info', details = {}) {
-  // Prevent recursive logging which can occur during configuration loading
-  if (SecurityUtils._logging) {
-  return;
-  }
-  
-  SecurityUtils._logging = true;
-  try {
-  const cfg = getConfigManager()?.getConfig?.() || {};
-  const envLevel = (process.env.SECURITY_LOG_LEVEL || process.env.I18NTK_SECURITY_LOG_LEVEL || '').toLowerCase();
-  const configLevel = (cfg.security?.logLevel || cfg.security?.audit?.logLevel || '').toLowerCase();
-  
-  // Check for debug mode
-  const debugMode = process.env.I18N_DEBUG === 'true' || process.env.DEBUG === 'true';
-  const currentLevel = debugMode ? 'info' : (envLevel || configLevel || 'warn');
-
-      const levels = { error: 0, warn: 1, warning: 1, info: 2 };
-      const messageLevel = levels[level.toLowerCase()] ?? 2;
-      const allowedLevel = levels[currentLevel] ?? 1;
-      if (messageLevel > allowedLevel) {
-        return;
-      }
-
-      const timestamp = new Date().toISOString();
-      const logEntry = {
-        timestamp,
-        level,
-        event,
-        details: {
-          ...details,
-          pid: process.pid,
-          nodeVersion: process.version
-        }
-      };
-
-      const message = `[SECURITY ${level.toUpperCase()}] ${timestamp}: ${event}`;
-      if (level === 'error') {
-        console.error(message, details);
-      } else if (level === 'warn' || level === 'warning') {
-        console.warn(message, details);
-      } else {
-        console.log(message, details);
-      }
-    } finally {
-      SecurityUtils._logging = false;
-    }
-  }
+  static logSecurityEvent(event, level = 'info', details = {}) {
+    if (SecurityUtils._logging) {
+      return;
+    }
+
+    SecurityUtils._logging = true;
+    try {
+      const debugMode = logger.isDebugMode();
+      const explicitSecurityLogs = process.env.I18NTK_ENABLE_SECURITY_LOGS === 'true';
+      const source = details && details.source ? String(details.source).toLowerCase() : 'internal';
+      const levelName = String(level || 'info').toLowerCase();
+      const normalizedLevel = levelName === 'warning' ? 'warn' : levelName;
+
+      // Security warnings from internal paths are noise during builds.
+      if (!debugMode && !explicitSecurityLogs && source !== 'user') {
+        return;
+      }
+
+      logger.security(normalizedLevel, event, {
+        ...details,
+        pid: process.pid,
+        nodeVersion: process.version
+      });
+    } finally {
+      SecurityUtils._logging = false;
+    }
+  }
 
   // Add other static methods here...
-  static validatePath(filePath, basePath = process.cwd(), verbose = false) {
-    const i18n = getI18n();
-    const useI18n = i18n && i18n.isInitialized && typeof i18n.t === 'function';
-
-    try {
+  static validatePath(filePath, basePath = process.cwd(), verbose = false) {
+    const i18n = getI18n();
+    const useI18n = i18n && i18n.isInitialized && typeof i18n.t === 'function';
+
+    try {
     // Check against whitelist patterns for our own package artifacts
     if (SecurityUtils.PACKAGE_ARTIFACT_WHITELIST.some(pattern => pattern.test(filePath))) {
     return filePath;
@@ -195,17 +247,42 @@ static _logging = false;
         return null;
       }
 
-      // Check for obvious dangerous patterns first
-      if (!SecurityUtils.isSafePath(filePath)) {
-        const message = useI18n
-          ? i18n.t('security.pathTraversalAttempt')
-          : 'Path traversal attempt';
-        SecurityUtils.logSecurityEvent(message, 'warning', {
-          inputPath: filePath,
-          reason: 'Contains dangerous patterns'
-        });
-        return null;
-      }
+      const isWindowsAbsolute = /^[A-Z]:[\/\\]/i.test(filePath);
+      const isUnixAbsolute = filePath.startsWith('/') || filePath.startsWith('\\');
+      const isAbsolutePath = isWindowsAbsolute || isUnixAbsolute;
+      const dangerousReason = detectDangerReason(filePath);
+      const source = isInternalPath(filePath) ? 'internal' : 'user';
+
+      if (isAbsolutePath && isInternalPath(filePath)) {
+        return path.resolve(filePath);
+      }
+
+      // For absolute paths, defer trust decision to base-path containment checks below,
+      // but still reject obvious shell/injection markers.
+      if (isAbsolutePath && dangerousReason) {
+        const message = useI18n
+          ? i18n.t('security.pathTraversalAttempt')
+          : 'Path traversal attempt';
+        SecurityUtils.logSecurityEvent(message, 'warning', {
+          inputPath: filePath,
+          reason: dangerousReason,
+          source
+        });
+        return null;
+      }
+
+      // Check for obvious dangerous patterns first for relative paths
+      if (!isAbsolutePath && !SecurityUtils.isSafePath(filePath)) {
+        const message = useI18n
+          ? i18n.t('security.pathTraversalAttempt')
+          : 'Path traversal attempt';
+        SecurityUtils.logSecurityEvent(message, 'warning', {
+          inputPath: filePath,
+          reason: dangerousReason || 'Contains unsafe path segments',
+          source
+        });
+        return null;
+      }
 
       // Resolve base and target paths
       const base = fs.realpathSync(basePath);
@@ -220,44 +297,47 @@ static _logging = false;
       }
 
       // Check for actual path traversal (going outside the base directory)
-      const relativePath = path.relative(base, finalPath);
-      if (relativePath.startsWith('..')) {
-        const message = useI18n
-          ? i18n.t('security.pathTraversalAttempt')
-          : 'Path traversal attempt';
-        SecurityUtils.logSecurityEvent(message, 'warning', {
-          inputPath: filePath,
-          resolvedPath: finalPath,
-          basePath: base,
-          relativePath: relativePath
-        });
-        return null;
-      }
+      const relativePath = path.relative(base, finalPath);
+      if (relativePath.startsWith('..')) {
+        const message = useI18n
+          ? i18n.t('security.pathTraversalAttempt')
+          : 'Path traversal attempt';
+        SecurityUtils.logSecurityEvent(message, 'warning', {
+          inputPath: filePath,
+          resolvedPath: finalPath,
+          basePath: base,
+          relativePath: relativePath,
+          source
+        });
+        return null;
+      }
 
       // Allow absolute paths that resolve within the project structure
       // The isSafePath check above already filtered out dangerous absolute paths
 
       if (verbose) {
-        const successMsg = useI18n
-          ? i18n.t('security.pathValidated')
-          : 'Path validated';
-        SecurityUtils.logSecurityEvent(successMsg, 'info', {
-          inputPath: filePath,
-          resolvedPath: finalPath
-        });
-      }
-      return finalPath;
+        const successMsg = useI18n
+          ? i18n.t('security.pathValidated')
+          : 'Path validated';
+        SecurityUtils.logSecurityEvent(successMsg, 'info', {
+          inputPath: filePath,
+          resolvedPath: finalPath,
+          source
+        });
+      }
+      return finalPath;
     } catch (error) {
       const message = useI18n
         ? i18n.t('security.pathValidationError')
         : 'Path validation error';
-      SecurityUtils.logSecurityEvent(message, 'error', {
-        inputPath: filePath,
-        error: error.message
-      });
-      return null;
-    }
-  }
+      SecurityUtils.logSecurityEvent(message, 'error', {
+        inputPath: filePath,
+        error: error.message,
+        source: isInternalPath(filePath) ? 'internal' : 'user'
+      });
+      return null;
+    }
+  }
 
   static safeExistsSync(filePath, basePath, timeoutMs = 3000) {
     return this.withTimeoutSync(() => {
@@ -489,21 +569,23 @@ static _logging = false;
   const resolvedPath = path.resolve(joinedPath);
   
   // Ensure the final path is within the base directory
-  if (!resolvedPath.startsWith(resolvedBase)) {
-  SecurityUtils.logSecurityEvent('Path traversal attempt detected in safeJoin', 'error', {
-  basePath,
-  paths,
-  resolvedPath
-  });
-  return false;
-  }
+  if (!resolvedPath.startsWith(resolvedBase)) {
+  SecurityUtils.logSecurityEvent('Path traversal attempt detected in safeJoin', 'error', {
+  basePath,
+  paths,
+  resolvedPath,
+  source: 'internal'
+  });
+  return false;
+  }
   return resolvedPath;
   } catch (error) {
-  SecurityUtils.logSecurityEvent('Error in safeJoin', 'error', {
-  basePath,
-  paths,
-  error: error.message
-  });
+  SecurityUtils.logSecurityEvent('Error in safeJoin', 'error', {
+  basePath,
+  paths,
+  error: error.message,
+  source: 'internal'
+  });
   return false;
   }
   }
@@ -551,11 +633,12 @@ static _logging = false;
     ];
 
     // Allow absolute paths that are within the project structure
-    if (filePath.startsWith('/') || filePath.startsWith('\\')) {
-      // Allow absolute paths but check for dangerous patterns
-      const hasDangerousPatterns = dangerousPatterns.slice(1).some(pattern => pattern.test(filePath));
-      return !hasDangerousPatterns;
-    }
+    if (filePath.startsWith('/') || filePath.startsWith('\\')) {
+      // Treat raw Unix-style absolute input as dangerous by default in this helper.
+      // `validatePath` can still permit absolute paths if they resolve within basePath.
+      const hasDangerousPatterns = dangerousPatterns.slice(1).some(pattern => pattern.test(filePath));
+      return !hasDangerousPatterns;
+    }
 
     return !dangerousPatterns.some(pattern => pattern.test(filePath));
   }