Improve package.json startup scripts with environment validation and logging

[Copilot]

Overview

This PR enhances the stability and developer experience of the Quirk bot by implementing comprehensive environment file validation with clear, user-friendly error messages in English.

Problem

Previously, the application would:

• Start without validating required environment files exist
• Use generic dotenv.config() without specifying which .env file to load
• Crash with unclear errors when environment variables were missing
• Not distinguish between development and production environments clearly

Solution

1. Environment-Specific Configuration Files

• Development mode now explicitly uses .env.local
• Production mode now explicitly uses .env.production
• This separation prevents accidental use of development config in production

2. Pre-Flight Validation

All startup scripts now validate environment files before running expensive operations (database migrations, builds, etc.):

$ npm run dev

🔍 Checking environment configuration for development mode...
📁 Looking for: .env.local

❌ ERROR: Required environment file ".env.local" not found!

📝 Please create the file ".env.local" in the project root.
💡 You can use ".env.template" as a reference.

ℹ️  A template file exists at: .env.template
   You can copy it using: cp .env.template .env.local

3. Centralized Environment Loading

Created src/config/env-loader.ts that:

• Automatically selects the correct env file based on NODE_ENV
• Provides detailed startup logging
• Exits gracefully with helpful messages if configuration is missing
• Ensures consistent environment loading across the application

4. Updated Package.json Scripts

New scripts:

• check-env:dev - Validates .env.local exists
• check-env:prod - Validates .env.production exists

Enhanced scripts:

• dev:app, dev:pair - Now validate .env.local before starting
• start, start:direct, start:node, prebuild - Now validate .env.production before running
• start:node - Explicitly sets NODE_ENV=production for clarity

Files Changed

Added:

• scripts/check-env.js - Environment file validation script
• src/config/env-loader.ts - Centralized environment loader module
• scripts/test-env-validation.js - Comprehensive test suite

Modified:

• package.json - Updated scripts with validation checks
• src/start.ts - Uses new centralized env loader
• src/configuration/general.ts - Uses new centralized env loader
• .gitignore - Added .env.production to prevent accidental commits
• README.md - Added environment configuration documentation

Testing

• ✅ All automated tests pass (see scripts/test-env-validation.js)
• ✅ Code review passed with no issues
• ✅ Security scan found no vulnerabilities
• ✅ TypeScript builds successfully
• ✅ Validated both development and production startup flows

Migration Guide

For existing installations:

Development:

cp .env.template .env.local
# Edit .env.local with your configuration
npm run dev

Production:

cp .env.template .env.production
# Edit .env.production with your configuration
npm run start

Benefits

• 🛡️ Improved stability - Catches configuration issues before app crashes
• 🚀 Better DX - Clear, actionable error messages save debugging time
• 🔒 Production safety - Explicit separation prevents config mistakes
• 📝 Better logging - Know exactly which env file is being loaded
• ✅ Easier onboarding - New developers get helpful guidance

---

Resolves the issue of improving production and development command stability with better logging and environment file validation.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• checkpoint.prisma.io
  • Triggering command: /usr/local/bin/node /home/REDACTED/work/Quirk/Quirk/node_modules/prisma/build/child {"product":"prisma","version":"5.22.0","cli_install_type":"local","information":"","local_timestamp":"2025-10-24T19:05:46Z","project_hash":"c8208cdd","cli_path":"/home/REDACTED/work/Quirk/Quirk/node_modules/.bin/prisma","cli_path_hash":"cffe18d0","endpoint":"REDACTED","disable":false,"arch":"x64","os":"linux","node_version":"v20.19.5","ci":true,"ci_name":"GitHub Actions","command":"generate","schema_providers":["postgresql"],"schema_preview_features":[],"schema_generators_providers":["prisma-client-js"],"cache_file":"/home/REDACTED/.cache/checkpoint-nodejs/prisma-cffe18d0","cache_duration":43200000,"remind_duration":172800000,"force":false,"timeout":5000,"unref":true,"child_path":"/home/REDACTED/work/Quirk/Quirk/node_modules/prisma/build/child","client_event_id":"","previous_client_event_id":"","check_if_update_available":true} (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

vamos melhorar a maneira que o package.json está iniciando o comando de produção e desenvolvimento, trazendo mais estabilidade e log caso aconteça algum problema ou erro, lembrando que sempre o produção vai usar o .env.production e o desenvolvimento vai rodar o .env.local e caso não tenha nenhum desses arquivos, vamos informar pro usuario isso em inglês

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.