instruqt/config/localVars.js

CLI tool for deploying AI agent context documentation across multiple platforms with dual MERN/module support

/**
 * @file Centralized configuration for the instruqt module
 * @description Defines constants and environment variables for the application.
 * 
 * RATIONALE: Centralizes all deployment targets and context mappings to ensure
 * consistency across the entire application. Changes here automatically propagate
 * to all deployment operations without requiring updates in multiple files.
 * 
 * DESIGN DECISIONS:
 * 1. RULE_DIRS: These specific directories were chosen to support major AI development platforms:
 *    - .roo/rules: Roo Code editor (emerging AI-powered development platform)
 *    - .kilocode/rules: Cline/Kilo Code (VS Code extension for AI assistance)  
 *    - .clinerules: Legacy support for older AI agent configurations
 *    
 * 2. CONTEXT_MODES: Maps user-friendly names to actual directory names.
 *    - 'mern' → 'mern_context': Default mode for full-stack web development
 *    - 'module' → 'npm_context': Focused mode for NPM packages and utilities
 *    
 * 3. Environment Variables: Added support for runtime configuration without
 *    modifying core constants. This allows customization in different environments
 *    while maintaining stable defaults.
 *    
 * ENHANCED FEATURES:
 * - Environment variable validation and warnings
 * - Performance monitoring configuration
 * - Debug and logging level controls
 */

const os = require('os');
const {
  getEnv,
  getInt, 
  getMissingEnvVars,
  warnIfMissingEnvVars,
  logInfo
} = require('../lib/qerrorsAdapter');

// 🚫 PROTECTED: DO NOT EDIT (READ ONLY)
// These constants define the core behavior of the instruqt deployment system.
// Changes here affect all deployment operations and should be made carefully.
const RULE_DIRS = ['.roo/rules', '.kilocode/rules', '.clinerules'];
const CONTEXT_MODES = {
  npm: 'contexts/npm',         // For NPM packages and utility libraries
  mern: 'contexts/mern',       // For full-stack web applications
  fastapi: 'contexts/fastapi'  // For FastAPI Python backend applications
};
// └── END PROTECTED RANGE 🚫

// Test files configuration moved from qtests-runner.js global scope
const TEST_FILES = [
  { name: 'instruqt', path: './lib/instruqt.test' },        // Core functionality tests
  { name: 'testUtils', path: './lib/testUtils.test' },      // Test infrastructure validation
  { name: 'packs', path: './lib/packs.test' },              // Pack system tests
  { name: 'mainModule', path: './index.test' },             // Main module exports tests
  { name: 'CLI', path: './bin/cli.test' },                  // Command line interface tests
  { name: 'config', path: './config/localVars.test' },      // Configuration constants tests
  { name: 'example', path: './example.test' },              // Example usage tests
  { name: 'testHarness', path: './lib/testHarness.test' },  // Test harness validation tests
  { name: 'enhanced-testing-demo', path: './examples/enhanced-testing-demo' }  // Enhanced qtests capabilities demo
];

// Integration test files configuration moved from qtests-runner.js global scope
const INTEGRATION_TEST_FILES = [
  { name: 'api-integration', path: './tests/api-integration.test' },          // API workflow integration tests
  { name: 'cli-integration', path: './tests/cli-integration.test' },          // CLI interface integration tests  
  { name: 'cross-module-integration', path: './tests/cross-module-integration.test' }, // Cross-module integration tests
  { name: 'workflow-integration', path: './tests/workflow-integration.test' }  // Key workflow integration tests
];

// Pack system configuration candidates moved from lib/packs.js global scope
const PACK_CONFIG_CANDIDATES = ['instruqt.config.json', '.instruqt.json'];

// Environment-configurable settings
// These can be customized via environment variables for different deployment contexts
const OPTIONAL_ENV_VARS = [
  'INSTRUQT_LOG_LEVEL',
  'INSTRUQT_TEMP_DIR', 
  'INSTRUQT_VERBOSE',
  'INSTRUQT_PERFORMANCE_MONITORING'
];

// Check for optional environment variables and warn if missing (non-critical)
warnIfMissingEnvVars(OPTIONAL_ENV_VARS);

// Default configuration fallback object (moved from index.js and bin/cli.js)
const DEFAULT_CONFIG = {
  RULE_DIRS,
  CONTEXT_MODES
};

// Environment-based configuration with sensible defaults
const ENV_CONFIG = {
  LOG_LEVEL: getEnv('INSTRUQT_LOG_LEVEL', 'info'),
  TEMP_DIR: getEnv('INSTRUQT_TEMP_DIR', os.tmpdir()),
  VERBOSE: (getEnv('INSTRUQT_VERBOSE', 'false') || 'false').toLowerCase() === 'true',
  PERFORMANCE_MONITORING: (getEnv('INSTRUQT_PERFORMANCE_MONITORING', 'true') || 'true').toLowerCase() === 'true',
  TEST_TIMEOUT: getInt('INSTRUQT_TEST_TIMEOUT', 30000), // 30 seconds default
  MAX_PARALLEL_TESTS: getInt('INSTRUQT_MAX_PARALLEL_TESTS', 1) // Sequential by default
};

// Log configuration on startup for transparency
logInfo('Instruqt configuration loaded', {
  ruleDirectories: RULE_DIRS.length,
  contextModes: Object.keys(CONTEXT_MODES).length,
  environmentOverrides: ENV_CONFIG
});

/**
 * Robust config loading utility that provides fallbacks
 * Used consistently across index.js and bin/cli.js
 */
function loadConfigWithFallbacks() {
  try {
    const config = require('./localVars');
    if (!config.RULE_DIRS || !config.CONTEXT_MODES) {
      throw new Error('Config loaded but missing required properties');
    }
    return config;
  } catch (error) {
    return DEFAULT_CONFIG;
  }
}

module.exports = {
  RULE_DIRS,
  CONTEXT_MODES,
  ENV_CONFIG,
  OPTIONAL_ENV_VARS,
  DEFAULT_CONFIG,
  TEST_FILES,
  INTEGRATION_TEST_FILES,
  PACK_CONFIG_CANDIDATES,
  loadConfigWithFallbacks
};