docs(cli): add parser migration guardrails#2860
Open
sjinks wants to merge 1 commit into
Open
Conversation
## Purpose and Context PLTFRM-2357 tracks a follow-up from a VIP CLI 4.0.1 parser compatibility incident. The migration guidance should explicitly call out argument shapes that previously relied on implicit args/mri behavior. ## Key Changes - Document short-option equals normalization for value-taking aliases. - Document post-parse default handling for parser-backed options. - Note the regression test that guards the compatibility contract. ## Impact and Considerations This is a documentation-only change. It does not change CLI runtime behavior or release packaging. ## Testing and Validation Ran `npm run format:check`. Refs PLTFRM-2357
Contributor
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
|
Contributor
There was a problem hiding this comment.
Pull request overview
This documentation-only PR adds guardrails for future CLI parser migration work, focusing on preserving option parsing compatibility during Commander-related refactors.
Changes:
- Documents short-option equals normalization behavior.
- Documents post-parse default application for parser-backed options.
- Adds the same migration guardrails to the agent-facing contributor guide.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
docs/COMMANDER-MIGRATION.md |
Adds preserved compatibility behavior for short-option equals syntax and tracked defaults. |
AGENTS.md |
Adds parser migration guardrails for future agents working on CLI parser changes. |
| - Watch shared state: current implementation mutates a global; ensure new parser avoids cross-command bleeding when multiple command instances run in-process (tests/CLI wrappers). | ||
| - Login guardrails in `vip.js` let certain commands bypass auth; preserve equivalent shortcuts or add explicit non-interactive flags for CI. | ||
| - Normalize short-option equals syntax: rewrite `-x=value` to `-x value` before parsing for short options that expect values; track which short options take values to avoid breaking boolean flags that should remain flag-only. | ||
| - Apply tracked defaults after parsing: when an option has both a default and a custom parser function, apply the default only when `opts[optionName] === undefined` after the parser runs, so that explicit values and defaults maintain parity with the parser contract (see test `parses short options using equals syntax without prefixing values` in `__tests__/lib/cli/command.js`). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Document parser migration guardrails for short-option equals syntax and parser-backed option defaults. This captures compatibility details that should stay explicit during future CLI parser work.
Changelog Description
Changed
Pull request checklist
New release checklist
npm run format:check.Steps to Test
AGENTS.md.docs/COMMANDER-MIGRATION.md.npm run format:check.