Overhauls configuration system and stabilizes Node.js runtime#4
Overhauls configuration system and stabilizes Node.js runtime#4amannirala13 wants to merge 4 commits intomainfrom
Conversation
BREAKING CHANGE: Auto-loading removed
## Phase 1 Complete: Remove Auto-Load Race Condition
### Breaking Changes
- Removed config.ts auto-load entry point
- Removed register.ts --require hook
- Removed exports for ./config and ./register
- All users MUST use explicit async API
### Reason
The auto-load implementation had a critical race condition where the
async IIFE returned immediately without waiting for secrets to load,
causing process.env secrets to be undefined.
### Migration Required
Before (v0.2.x - broken):
```js
require('@envguard/node/config');
console.log(process.env.API_KEY); // undefined!
```
After (v0.3.0 - fixed):
```js
(async () => {
await require('@envguard/node').config();
console.log(process.env.API_KEY); // Works!
})();
```
### Changes
- Delete config.ts and register.ts
- Update package.json exports (remove config/register)
- Update tsup.config.ts (remove from build)
- Update README with async-only examples
- Add MIGRATION_GUIDE_V03.md
- Update CHANGELOG with v0.3.0 breaking changes
- Version bump: 0.2.0 → 0.3.0
### Testing
- All 88 tests passing ✅
- Build successful ✅
- No config/register in dist ✅
### Next Steps
- Phase 2: PackageNameResolver
- Phase 3: Config v2 schema
- Phase 4-7: Full enterprise config system
See IMPLEMENTATION_SPEC.md for complete roadmap.
Co-authored-by: Claude <noreply@anthropic.com>
Add PackageNameResolver with multi-strategy package name detection: - Reverse domain notation support (com.company.app) - NPM package name detection - Git remote URL parsing - Directory name fallback - Interactive package name selection in init command Key Changes: - packages/core/src/config/package-name-resolver.ts: New resolver class with 4 strategies (AUTO, REVERSE_DOMAIN, NPM, MANUAL) - packages/core/__tests__/config/package-name-resolver.test.ts: 19 comprehensive tests - packages/cli/src/commands/init.action.ts: Updated to use PackageNameResolver with interactive prompts - packages/core/src/config/index.ts: Export new resolver types Features: - Auto-detect package names from package.json, git remotes, or directory - Validate package names (no spaces, valid chars, reverse domain recommended) - Convert npm names to reverse domain (e.g., @envguard/node → dev.envguard.node) - Parse git URLs (SSH and HTTPS) to reverse domain format - Interactive selection with suggestions marked as "(recommended)" - Multi-language project support (no package.json dependency) Tests: All 19 PackageNameResolver tests passing Build: Clean builds for core and cli packages 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
… (Phase 3) Add comprehensive v2 configuration system with enhanced structure, automatic migration, and backward compatibility with v1 configs. Core Changes: - packages/core/src/config/config.ts: Add EnvGuardConfigV2 class with 8 structured interfaces * IPackageConfig: name, displayName, type (reverse-domain/npm/manual) * IEnvironmentConfig: allowed list, default, naming mode (strict/relaxed) * IPathsConfig: template and manifest paths * IValidationConfig: enabled, strictMode, enforceRotation * ISecurityConfig: auditLog, requireConfirmation, allowedCommands * IManifestConfig: version, autoSync * IConfigMetadata: created, lastModified, modifiedBy * 13 getter methods, updateMetadata(), isValid(), createDefault() - packages/core/src/config/config-migrator.ts: Automatic v1→v2 migration system * detectVersion(): Detect v1 or v2 config from file * migrateV1ToV2(): Convert v1 to v2 preserving settings * backupV1Config(): Create timestamped backup before migration * performMigration(): Full migration with backup + validation * needsMigration(): Check if migration required * loadConfig(): Unified loader for both v1 and v2 - packages/core/src/config/config.manager.ts: Support both v1 and v2 * load(): Returns v1 or v2 instance * loadOrMigrate(): Auto-migrates v1→v2 transparently * createV2(): Create new v2 config (default for new projects) * getPackageName(): Handle both v1.getPackage() and v2.getPackageName() * update(): Update v1 or v2 with type-safe field mapping - packages/core/src/config/config.parser.ts: Handle both versions * writeToFile(): Accept EnvGuardConfig | EnvGuardConfigV2 * serializeToJSON(): Serialize v1 or v2 to JSON Updated Components: - packages/cli/src/commands/init.action.ts: Use createV2() for new projects - packages/node/src/loader/index.ts: Support both v1 and v2 package name getters - packages/core/src/config/index.ts: Export all v2 types and classes Tests: - packages/core/__tests__/config/config-v2.test.ts: 23 tests for EnvGuardConfigV2 * createDefault with different package types * All getter methods * isEnvironmentAllowed validation * updateMetadata functionality * isValid comprehensive validation * toObject serialization - packages/core/__tests__/config/config-migrator.test.ts: 16 tests for migration * detectVersion for v1, v2, invalid, missing * migrateV1ToV2 with field preservation * backupV1Config file creation * performMigration full workflow * needsMigration detection * loadConfig unified loading Benefits: - Multi-language support via reverse domain notation - Environment management with allowed list (prevent typos) - Validation and security policies - Metadata tracking for audit trails - Automatic migration preserves user settings - Backward compatible - old projects continue to work - Enterprise-ready configuration structure All Tests Passing: - @envguard/core: 58 tests (19 + 23 + 16 new) - @envguard/node: 88 tests - @envguard/cli: 19 tests - Build: Clean for all packages 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Add comprehensive config management commands with 7 subcommands for
viewing, editing, validating, backing up, and migrating configurations.
New Commands:
- envg config get <key>: Get config value with dot notation support
* Examples: envg config get package.name, envg config get environments.default
* Returns formatted JSON for objects, plain values for primitives
- envg config set <key> <value>: Set config value with dot notation
* Auto-migrates v1→v2 before setting values
* Updates metadata timestamps automatically
* Type-safe value conversion (boolean, number, array, string)
- envg config list: Display complete configuration as JSON
* Works with both v1 and v2 configs
* Pretty-printed output
- envg config validate: Validate current configuration
* Checks all required fields
* Validates environment consistency (default must be in allowed list)
* Provides detailed error messages for v2 configs
- envg config backup: Create timestamped backup
* Default path: .envguard/config.backup.{timestamp}.json
* Custom path via --output flag
- envg config restore <file>: Restore from backup
* Auto-creates backup of current config before restoring
* Validates backup file format
* Supports both v1 and v2 backups
- envg config migrate: Migrate v1→v2 manually
* Auto-detects current version
* Creates backup before migration
* Skips if already v2
Implementation Details:
- packages/cli/src/commands/config.action.ts: Core implementation (430 lines)
* configGetAction: Nested object access with dot notation
* configSetAction: Type-aware value setting with auto-migration
* configListAction: Pretty JSON display
* configValidateAction: Comprehensive validation with detailed errors
* configBackupAction: Timestamped backup creation
* configRestoreAction: Safe restore with auto-backup
* configMigrateAction: v1→v2 migration workflow
* Helper functions: getNestedValue(), setNestedValue()
- packages/cli/src/cli.ts: Command registration
* Registered config command with 7 subcommands
* Commander.js subcommand pattern
* Consistent --verbose flag support
- packages/cli/src/commands/index.ts: Export config actions
Features:
- Dot notation for nested config access (e.g., "package.name", "environments.allowed")
- Auto-migration from v1→v2 when setting values
- Metadata tracking (lastModified, modifiedBy)
- Safe restore with automatic backup creation
- Type-safe value conversion (string→boolean/number/array)
- Comprehensive validation with actionable error messages
- Timestamped backups for audit trails
CLI Help Output:
$ envg config --help
Usage: envg config [options] [command]
Manage EnvGuard configuration
Commands:
get [options] <key> Get a config value (supports dot notation)
set [options] <key> <value> Set a config value (supports dot notation)
list [options] List all config values
validate [options] Validate current config
backup [options] Backup current config
restore [options] <file> Restore config from backup
migrate [options] Migrate config from v1 to v2
All Tests Passing:
- @envguard/core: 58 tests
- @envguard/node: 88 tests
- @envguard/cli: 12 tests
- Build: Clean for all packages
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| const configManager = new ConfigManager(); | ||
| let config = await configManager.load(); | ||
|
|
||
| if (!config) { | ||
| error('EnvGuard not initialized. Run "envg init" first.'); | ||
| process.exit(1); | ||
| } | ||
|
|
||
| // Auto-migrate to v2 if needed | ||
| if (!(config instanceof EnvGuardConfigV2)) { | ||
| info('Migrating config to v2...'); | ||
| config = await configManager.loadOrMigrate(); | ||
| if (!config) { | ||
| error('Migration failed'); | ||
| process.exit(1); | ||
| } | ||
| } | ||
|
|
||
| // Set the value | ||
| const success = setNestedValue(config, key, value); | ||
| if (!success) { | ||
| error(`Cannot set config key "${key}"`); | ||
| process.exit(1); | ||
| } | ||
|
|
||
| // Update metadata | ||
| config.updateMetadata('envg-cli'); | ||
|
|
||
| // Save | ||
| await configManager.save(config); |
There was a problem hiding this comment.
After configSetAction loads the config via ConfigManager.load, the variable has the union type EnvGuardConfig | EnvGuardConfigV2. The later call to config.updateMetadata('envg-cli') and the argument to configManager.save(config) both require an EnvGuardConfigV2, but the variable is never narrowed or cast. Running the TypeScript build fails with “Property 'updateMetadata' does not exist on type 'EnvGuardConfig | EnvGuardConfigV2'” and “Argument of type 'EnvGuardConfig | EnvGuardConfigV2' is not assignable to parameter of type 'EnvGuardConfig'.” The commit therefore does not compile; narrow the type after migration or update the save signature to handle v2 configs.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull Request Overview
This PR addresses critical architectural gaps and reliability issues in EnvGuard, preparing it for enterprise adoption. The changes include a configuration system overhaul introducing v2 schema with enhanced capabilities, and a fix for a race condition in the Node.js runtime by removing problematic auto-loading mechanisms.
Key changes:
- Introduces Config v2 schema with structured package configuration, environment management, and validation policies
- Adds comprehensive CLI commands (
envg configsuite) for configuration management - Implements automatic v1 to v2 config migration with backup functionality
- Removes auto-loading from
@envguard/nodeto fix race conditions; requires explicit async initialization - Adds
PackageNameResolversupporting reverse domain notation for globally unique identifiers
Reviewed Changes
Copilot reviewed 23 out of 23 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/node/src/register.ts | Removed auto-load hook for --require flag |
| packages/node/src/config.ts | Removed auto-load entry point module |
| packages/node/tsup.config.ts | Removed build entries for removed modules |
| packages/node/package.json | Removed package exports and bumped version to 0.3.0 |
| packages/node/README.md | Updated usage examples to show explicit async initialization |
| packages/node/MIGRATION_GUIDE_V03.md | Added comprehensive migration guide for v0.3.0 breaking changes |
| packages/node/CHANGELOG.md | Documented breaking changes and migration path |
| packages/node/src/loader/index.ts | Added backward compatibility check for v1 config |
| packages/core/src/config/package-name-resolver.ts | New multi-strategy package name resolution system |
| packages/core/src/config/config.ts | Added v2 config schema with enhanced structure |
| packages/core/src/config/config-migrator.ts | New config migration utilities for v1→v2 |
| packages/core/src/config/config.manager.ts | Added v2 support and auto-migration capability |
| packages/core/src/config/config.parser.ts | Extended to support both v1 and v2 configs |
| packages/core/src/config/index.ts | Exported new v2 types and utilities |
| packages/cli/src/commands/config.action.ts | New config management command implementations |
| packages/cli/src/commands/init.action.ts | Enhanced with interactive package name selection |
| packages/cli/src/commands/index.ts | Exported new config commands |
| packages/cli/src/cli.ts | Registered new config command suite |
| packages/core/tests/config/*.test.ts | Comprehensive test coverage for v2 features |
| IMPLEMENTATION_SPEC.md | Detailed technical specification document |
| ARCHITECTURE_AUDIT.md | Architecture assessment and rationale |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### | ||
|
|
||
| Removed | ||
|
|
There was a problem hiding this comment.
Incomplete section heading. Should be '### Removed' instead of '###' followed by a blank line and then 'Removed'.
| ### | |
| Removed | |
| ### Removed |
| const sshMatch = gitRemote.match(/git@([^:]+):([^/]+)\/([^.]+)\.git/); | ||
| if (sshMatch && sshMatch[1] && sshMatch[2] && sshMatch[3]) { | ||
| const [, host, org, repo] = sshMatch; |
There was a problem hiding this comment.
Array destructuring creates unused first element. Use explicit indices instead: const host = sshMatch[1]; const org = sshMatch[2]; const repo = sshMatch[3]; for clarity and to avoid confusion.
| /https?:\/\/([^/]+)\/([^/]+)\/([^.]+)\.git/ | ||
| ); | ||
| if (httpsMatch && httpsMatch[1] && httpsMatch[2] && httpsMatch[3]) { | ||
| const [, host, org, repo] = httpsMatch; |
There was a problem hiding this comment.
Same array destructuring issue as with sshMatch. Use explicit indices for clarity: const host = httpsMatch[1]; const org = httpsMatch[2]; const repo = httpsMatch[3];
| const [, host, org, repo] = httpsMatch; | |
| const host = httpsMatch[1]; | |
| const org = httpsMatch[2]; | |
| const repo = httpsMatch[3]; |
| // Parse as array | ||
| try { | ||
| target[lastKey] = JSON.parse(value); | ||
| } catch { |
There was a problem hiding this comment.
Silent failure in catch block makes debugging difficult. Log or throw an error explaining that array parsing failed: catch (e) { logger.error('Failed to parse array value:', e); return false; }
| } catch { | |
| } catch (e) { | |
| error('Failed to parse array value:', e); |
amannirala13
added
bug
There was a problem hiding this comment.
💡 Codex Review
envguard/packages/cli/src/commands/init.action.ts
Lines 132 to 136 in 94a1119
Handle v2 configs when checking existing initialization
When envg init runs in a project that already has a migrated v2 config, existing is an EnvGuardConfigV2. That class does not expose getPackage(), so the call existing.getPackage() throws TypeError: existing.getPackage is not a function and the command aborts before printing the warning. This means users cannot rerun envg init on a v2 project without the command crashing. Use the common ConfigManager.getPackageName() helper or branch on the config type to avoid calling a v1-only method.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| // 4. Create config (v2) | ||
| await configManager.createV2(packageName); | ||
|
|
||
| // 5. Show success message | ||
| success('\n✓ EnvGuard initialized successfully!'); |
There was a problem hiding this comment.
The init flow computes templateFile (either provided via --template or auto‑detected) and even reports it to the user, but createV2(packageName) ignores that value and writes a config whose paths.template is always the default .env.template. As a result, a project initialized with a custom or pre‑existing template ends up with a config pointing at the wrong file, so subsequent commands that rely on paths.template (validate, migrations, manifest generation) will operate on .env.template instead of the user’s chosen path. createV2 needs to accept the selected template path or the config should be updated after creation.
Useful? React with 👍 / 👎.
This pull request significantly enhances EnvGuard's core architecture and improves the reliability of the Node.js runtime, addressing critical architectural gaps for enterprise readiness.
Configuration System Overhaul (v0.3.0)
EnvGuardConfigV2structure with expanded capabilities. This includes:PackageNameResolver.envg configcommand suite (get,set,list,validate,backup,restore,migrate) for direct management of project configuration. This reduces the need for manualconfig.jsonedits and provides greater control and validation.ConfigMigratorto seamlessly upgrade existing v1 project configurations to the new v2 schema, ensuring a smooth transition with automatic backups.Node.js Runtime Stabilization (v0.3.0)
@envguard/noderuntime where secrets were not guaranteed to be available due to asynchronous auto-loading.require('@envguard/node/config')and the--requirehook) have been removed as breaking changes.await envguard.config()at the start of their application to ensure secrets are loaded synchronously and reliably.MIGRATION_GUIDE_V03.mdand updated documentation to assist users in adapting their Node.js applications to the new explicit loading pattern.