Overhauls Config System, Adds CLI Management & Fixes Node.js Loading

[amannirala13]

This release introduces significant architectural improvements to EnvGuard's configuration system, enabling enterprise readiness and addressing a critical race condition in the Node.js runtime.

Key Changes:

• Config System Overhaul (v2):

  • Implements a new EnvGuardConfigV2 schema, providing a more structured and extensible configuration format for projects.
  • Introduces a PackageNameResolver to support globally unique package identifiers, including reverse-domain notation, and provides validation and suggestions during project initialization (envg init).
  • Adds ConfigMigrator to automatically detect and migrate existing v1 configurations to the new v2 schema upon the first command execution, ensuring a smooth transition with automatic backups.
  • Enhances configuration with new fields for environment management, validation policies, security settings, and metadata.

• CLI Config Management:

  • Adds a comprehensive suite of new envg config commands: get, set, list, validate, backup, restore, and migrate.
  • Empowers users to manage all project configurations programmatically, reducing the need for manual file editing and providing immediate validation feedback.

• Node.js Runtime Fix (v0.3.0 Breaking Change):

  • Removes the problematic implicit auto-loading (require('@envguard/node/config') and Node.js --require hook) from the @envguard/node package.
  • Resolves a critical race condition that caused secrets to be unavailable at runtime by enforcing explicit asynchronous loading (await require('@envguard/node').config()).
  • Includes a detailed MIGRATION_GUIDE_V03.md to assist users in updating their Node.js applications to the new explicit loading pattern.

Benefits:

• Provides a robust, extensible, and future-proof configuration foundation for EnvGuard.
• Enables enterprise adoption by addressing critical architectural gaps around package identification and config management.
• Ensures reliable and consistent secret loading in Node.js applications, eliminating previous race conditions.
• Enhances the developer experience with powerful CLI tools for managing project configurations.

[Copilot]

Pull Request Overview

This PR introduces a comprehensive overhaul of EnvGuard's configuration system and addresses a critical race condition in the Node.js runtime. The changes enable enterprise adoption through improved package naming, structured configuration management, and explicit async secret loading.

Key Changes:

• Implements Config v2 schema with enhanced environment management, validation policies, and security settings
• Adds CLI commands for programmatic configuration management (envg config get/set/list/validate/backup/restore/migrate)
• Removes auto-loading from @envguard/node to fix race condition and enforces explicit async loading pattern

Reviewed Changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/node/package.json	Bumps version to 0.3.0 and removes config/register export endpoints
packages/node/src/config.ts	Removes auto-load module (breaking change)
packages/node/src/register.ts	Removes --require hook entry point (breaking change)
packages/node/src/loader/index.ts	Adds backward compatibility for v1/v2 config package name getters
packages/core/src/config/package-name-resolver.ts	Implements multi-strategy package name resolution with reverse-domain notation support
packages/core/src/config/config.ts	Adds EnvGuardConfigV2 class with structured configuration fields
packages/core/src/config/config-migrator.ts	Implements v1→v2 config migration with automatic backup
packages/core/src/config/config.manager.ts	Adds v2 config support and auto-migration capabilities
packages/cli/src/commands/init.action.ts	Updates init flow with interactive package name selection and validation
packages/cli/src/commands/config.action.ts	Implements config management CLI commands

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Array destructuring without verifying array length. The regex capture groups are checked for existence in the parent condition, but TypeScript doesn't guarantee the array indices exist. This could throw if the regex unexpectedly fails to capture all groups.

[Copilot]

Array destructuring without verifying array length. The regex capture groups are checked for existence in the parent condition, but TypeScript doesn't guarantee the array indices exist. This could throw if the regex unexpectedly fails to capture all groups.

[Copilot]

Hardcoded CLI version in default parameter creates maintenance burden. Consider obtaining version from package.json dynamically to keep it synchronized with actual releases.

[Copilot]

Hardcoded CLI version in default parameter creates maintenance burden. Consider obtaining version from package.json dynamically or accepting it as a required parameter to ensure version tracking accuracy.

[Copilot]

The modifiedBy value 'envg-cli' lacks version information. Consider including the CLI version (e.g., 'envg-cli@0.3.0') to track which version made the modification, consistent with the createDefault method.

[Copilot]

The templateFile variable is determined earlier in the function but is no longer passed to createV2(). This means the user's template file selection (including --template option and interactive prompts) is ignored, and only the default '.env.template' from createDefault() is used.

Suggested change

	await configManager.createV2(packageName);
	await configManager.createV2(packageName, templateFile);

[chatgpt-codex-connector]

💡 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".

[chatgpt-codex-connector]

Returning v2 config without updating callers breaks CLI commands

After load() was widened to return EnvGuardConfig | EnvGuardConfigV2, callers such as get.action.ts, check.action.ts, etc. still invoke config.getPackage()/config.getDefaultEnvironment() which only exist on the v1 class. Once init creates a v2 config, those commands will crash at runtime (TypeError: config.getPackage is not a function). Either adapt load() to provide a backward‑compatible interface or update the commands to use ConfigManager.getPackageName() / instanceof guards.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

ConfigManager.save can no longer accept v2 configs

save() still declares its parameter as EnvGuardConfig, but configSetAction now operates on EnvGuardConfigV2 instances and passes them into this method. Under the repo’s strict TypeScript settings the build will fail because EnvGuardConfigV2 is structurally incompatible with EnvGuardConfig. The method should accept a union or overload so both versions can be persisted without casting.

Useful? React with 👍 / 👎.

[gemini-code-assist]

Code Review

This is a substantial and well-thought-out pull request that significantly improves the configuration system, making it more robust and enterprise-ready. The introduction of the v2 config schema, the PackageNameResolver for multi-language support, and the comprehensive envg config CLI commands are excellent additions. The fix for the race condition in the Node.js package by enforcing explicit async loading is a critical improvement for reliability. The documentation, including the detailed architecture audit, implementation spec, and migration guides, is exemplary and shows great attention to detail. I've found a critical issue related to saving the new v2 config that will prevent the envg config set command from working, along with a few medium-severity suggestions to improve code clarity, maintainability, and user experience. Overall, this is a fantastic contribution that moves the project forward significantly.

[gemini-code-assist]

This action correctly attempts to save the modified v2 configuration. However, the configManager.save(config) call on line 149 will fail. The ConfigManager.save method in @envguard/core is currently typed to only accept an EnvGuardConfig (v1) instance, but here it is being passed an EnvGuardConfigV2 instance. This will cause a type error at compile time and a runtime failure.

To fix this, the ConfigManager.save method needs to be updated to accept both v1 and v2 config types, or a new generic save method should be used. For example:

// In packages/core/src/config/config.manager.ts
async save(config: EnvGuardConfig | EnvGuardConfigV2): Promise<void> {
  await this.parser.writeToFile(this.configPath, config);
}

Since ConfigManager.update already seems to handle both types via parser.writeToFile, another option could be to refactor this action to use configManager.update, though modifying save is the most direct fix.

[gemini-code-assist]

The validation logic for the package name is duplicated for the manual input flow (lines 66-75) and the custom name flow (lines 104-113). To improve maintainability and reduce redundancy, you could extract this validation logic into a separate helper function that can be reused in both inquirer prompts.

const validatePackageName = (input: string) => {
  const validation = PackageNameResolver.validate(input);
  if (!validation.valid) {
    return validation.error || 'Invalid package name';
  }
  if (validation.error) {
    // This is a non-blocking warning
    warn(validation.error);
  }
  return true;
};

// Then use it in both prompts:
// validate: validatePackageName

[gemini-code-assist]

The special handling for the allowed key, which requires the user to provide a JSON-formatted string for the array (e.g., '["dev", "prod"]'), is not very intuitive for a command-line interface. This could lead to user confusion and errors.

While dedicated commands like envg env add/remove are the long-term solution, for this generic set command, consider one of the following improvements:

• Disallow setting arrays: Throw an error if the user tries to set a value that is an array, and guide them to edit the file manually or wait for dedicated commands.
• Support comma-separated values: Parse a comma-separated string like "dev,prod" into an array. This is a more common CLI pattern.
• Add documentation: At a minimum, the command's description or help text should clarify the expected format for array values.

[gemini-code-assist]

This function falls back to 'local.my-app' if the input npmName is falsy (e.g., null or an empty string). While this provides a default, it happens implicitly. This could lead to unexpected behavior, for instance if detectNpmName returns null and this fallback is not the desired outcome.

To make the code more explicit and robust, consider adding a guard clause at the beginning of the function to handle falsy inputs clearly.

Suggested change

	static npmToReverseDomain(npmName: string): string {
	if (!npmName) {
	return 'local.my-app';
	}
	// @envguard/node → dev.envguard.node
	if (npmName.startsWith('@')) {
	const parts = npmName.slice(1).split('/');
	return `dev.${parts.join('.')}`;
	}
	// my-app → local.my-app
	return `local.${npmName}`;
	}
	static npmToReverseDomain(npmName: string): string {
	if (!npmName) {
	return 'local.my-app'; // Explicitly handle empty input
	}
	// @envguard/node → dev.envguard.node
	if (npmName.startsWith('@')) {
	const parts = npmName.slice(1).split('/');
	return `dev.${parts.join('.')}`;
	}
	// my-app → local.my-app
	return `local.${npmName}`;
	}

[amannirala13]

@gemini-code-assist review this PR

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive overhaul of the EnvGuard configuration system, including a new configuration schema (v2), CLI config management commands, and a fix for a race condition in the Node.js runtime. The changes aim to enhance enterprise readiness, improve developer experience, and ensure reliable secret loading. The review focuses on identifying potential issues related to correctness and security, as requested by the repository maintainer.

[gemini-code-assist]

This statement highlights critical architectural gaps. It would be beneficial to provide a brief overview of the existing architecture to give context to the identified gaps. This would help readers understand the severity and impact of these issues more effectively.

Consider adding a section briefly describing the current architecture before diving into the critical issues.

[gemini-code-assist]

Mitigation strategies are mentioned here. It would be helpful to elaborate on how "Automatic migration + backward compatibility" mitigates the risk of breaking changes for existing users. Providing specific details or examples can increase confidence in the proposed solution.

[gemini-code-assist]

The config command and its subcommands are registered directly within the cli.ts file. For better code organization and maintainability, consider moving the registration of these commands to a separate module or file (e.g., config-commands.ts) and importing them into cli.ts. This would improve the separation of concerns and make the code easier to navigate and test.

[gemini-code-assist]

The setNestedValue function modifies the config object directly. While this approach works, it might be beneficial to consider a more immutable approach where the function returns a new config object with the updated value. This can help prevent unintended side effects and make the code easier to reason about, especially as the config schema grows more complex.

[gemini-code-assist]

This logic handles type conversion for specific fields. Consider creating a more generic type conversion mechanism that can handle different data types and validation rules based on the config schema. This would make the code more extensible and easier to maintain as new config options are added.

[gemini-code-assist]

The name property in the choices array is being constructed by concatenating the s variable with a ternary operator. This can be simplified by using a template literal, which improves readability.

Consider using a template literal to construct the name property for better readability.

Suggested change

	name: `${s}${PackageNameResolver.isReverseDomain(s) ? ' (recommended)' : ''}`,
	value: s,
	})),
	name: `${s}${PackageNameResolver.isReverseDomain(s) ? ' (recommended)' : ''}`,

[gemini-code-assist]

The migrateV1ToV2 function uses a default CLI version. It would be better to pass the CLI version as an argument to ensure consistency and avoid hardcoding values. This makes the function more flexible and testable.

[gemini-code-assist]

The performMigration function catches any error during the migration process. It would be beneficial to implement more specific error handling to differentiate between different types of errors (e.g., file I/O errors, JSON parsing errors) and provide more informative error messages to the user.

[gemini-code-assist]

The regular expression ^[@a-zA-Z0-9._/-]+$ allows forward slashes, which might not be desirable in all contexts. Consider whether forward slashes should be explicitly allowed or disallowed based on the requirements for package names.

[gemini-code-assist]

This line indicates a breaking change. Consider adding a more direct link to the migration guide within this README for users who are upgrading.