From 1e20da4cc28c26e030041de6937b8e5e3b3fd74b Mon Sep 17 00:00:00 2001 From: Volodymyr Kolesnykov Date: Fri, 29 May 2026 19:17:05 +0300 Subject: [PATCH] docs(cli): add parser migration guardrails ## 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 --- AGENTS.md | 2 ++ docs/COMMANDER-MIGRATION.md | 1 + 2 files changed, 3 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 297250012..f0811f7be 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -96,3 +96,5 @@ Guide for future agents working on this codebase. Focus on traps, cross-cutting - Respect exit semantics: uncaught exceptions routed to `exit.withError`; GraphQL errors call `process.exit(1)` unless explicitly disabled; 401 auth errors exit with guidance. - 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`). diff --git a/docs/COMMANDER-MIGRATION.md b/docs/COMMANDER-MIGRATION.md index deea035e9..7cb5812b6 100644 --- a/docs/COMMANDER-MIGRATION.md +++ b/docs/COMMANDER-MIGRATION.md @@ -16,6 +16,7 @@ Goal: remove the abandoned `args` package, keep CLI behavior stable, and support - `_opts` controls are still honored: app/env context fetch, confirmation gating, output formatting, wildcard command handling, required positional args. - Shared formatting/output and telemetry hooks are still in the wrapper path. - Local nested subcommand dispatch still works via sibling executable resolution. +- Short-option equals normalization: `-x=value` is rewritten to `-x value` for short options expecting values before parsing; boolean short flags are not affected. Tracked option defaults are applied after parsing when the option remains undefined post-parse, preserving default+parser parity. ## Post-Migration Hardening