Commander migration

[rinatkhaziev]

Description

This pull request introduces several important updates to the CLI codebase, primarily focused on migrating from the args library to the more robust commander library for command-line argument parsing. It also adds comprehensive documentation for future contributors and updates dependency management files accordingly. These changes modernize the CLI infrastructure and provide clearer guidance for ongoing development.

Key changes include:

CLI Parser Migration:

• Replaced the args library with the commander library for CLI argument parsing, updating dependencies in both package.json and npm-shrinkwrap.json, and updating imports in src/lib/cli/command.js to use commander instead of args. [1] [2] [3] [4] [5] [6]
• Removed all references and dependencies related to args and its sub-dependencies (camelcase, leven, mri, etc.) from npm-shrinkwrap.json. [1] [2] [3] [4]

Documentation Improvements:

• Added a detailed AGENTS.md guide for future contributors, covering CLI architecture, traps, migration notes, and best practices for working with the codebase.
• Added a CLAUDE.md file referencing AGENTS.md for additional guidance.

Dependency Updates:

• Upgraded the commander package to version 14.0.3, ensuring compatibility with Node 20+ and updating the shrinkwrap and lock files to reflect the new version and its requirements. [1] [2]

These changes lay the groundwork for further CLI improvements and make the codebase easier to maintain and extend.

Pull request checklist

• Update SETUP.md with any new environmental variables.
• Update the documentation.
• Manually test the relevant changes.
• Follow the pull request checklist
• Add/update automated tests as needed.

New release checklist

• Automated tests pass.
• The Preparing for release checklist is completed.

Steps to Test

Outline the steps to test and verify the PR here.

Example:

1. Check out PR.
2. Run npm run build
3. Run ./dist/bin/vip-cookies.js nom
4. Verify cookies are delicious.

[sonarqubecloud]

Quality Gate passed

Issues
5 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull request overview

This PR migrates the VIP CLI’s argument parsing from the abandoned args package to a commander-backed compatibility wrapper, while also adding contributor-facing migration/architecture documentation and hardening some dev-env startup flows.

Changes:

• Replace args with a commander compatibility layer in src/lib/cli/command.js, and adjust root dispatch to await parsing.
• Add bounded readiness polling/retry behavior to dev-env start/exec flows to reduce Docker/Lando flakiness.
• Update dependencies (package.json, npm-shrinkwrap.json) and add migration/contributor docs (AGENTS.md, COMMANDER-MIGRATION.md, CLAUDE.md).

Reviewed changes

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

Show a summary per file

File	Description
src/lib/dev-environment/dev-environment-core.ts	Adds post-start readiness polling + one retry start pass before failing.
src/lib/cli/command.js	Replaces args with a commander-based compatibility wrapper, including subcommand spawning.
src/bin/vip.js	Awaits cmd.argv() so async parsing/dispatch completes reliably.
src/bin/vip-dev-env-exec.js	Adds bounded readiness polling before declaring an env “not running”.
package.json	Removes args, adds commander.
npm-shrinkwrap.json	Shrinkwrap updates to reflect dependency swap/removals.
docs/COMMANDER-MIGRATION.md	Documents migration status, preserved behaviors, and verification steps.
CLAUDE.md	Points contributors to AGENTS.md.
AGENTS.md	Adds detailed repo/CLI architecture and migration guidance.

Files not reviewed (1)

• npm-shrinkwrap.json: Language not supported

[Copilot]

executeSubcommand() re-injects an alias by scanning the raw argv after index 1, but this ignores the -- end-of-options convention used by parseEnvAliasFromArgv(). This can accidentally pick up alias-looking tokens intended for passthrough args (after --), duplicating/reordering them when spawning the child command. Consider only searching for/re-injecting an alias when parsedAlias.app is set, and limit the scan to arguments before -- (matching envAlias.ts behavior).

Suggested change

	const aliasFromRawArgv = argv.slice( 2 ).find( arg => isAlias( arg ) );
	const subcommandIndex = parsedAlias.argv.findIndex( ( arg, index ) => {
	return index > 1 && arg === subcommand;
	} );
	let childArgs = subcommandIndex > -1 ? parsedAlias.argv.slice( subcommandIndex + 1 ) : [];
	if ( aliasFromRawArgv ) {
	const endOfOptionsIndex = argv.indexOf( '--' );
	const aliasSearchArgs = endOfOptionsIndex === -1 ? argv.slice( 2 ) : argv.slice( 2, endOfOptionsIndex );
	const aliasFromRawArgv = aliasSearchArgs.find( arg => isAlias( arg ) );
	const subcommandIndex = parsedAlias.argv.findIndex( ( arg, index ) => {
	return index > 1 && arg === subcommand;
	} );
	let childArgs = subcommandIndex > -1 ? parsedAlias.argv.slice( subcommandIndex + 1 ) : [];
	if ( parsedAlias && parsedAlias.app && aliasFromRawArgv ) {

[Copilot]

startEnvironment() now has bounded readiness polling and a retry landoStart() pass. There are existing unit tests for dev-environment-core, but none cover the new success/retry/failure branches (e.g., isEnvUp false for N attempts then true; or always false leading to UserError). Adding mocked tests around this logic would prevent regressions and make the timing/retry behavior explicit.