Merge pull request #926 from tronprotocol/fix/output-formater-and-global-flag

feat(cli): allow known globals after command; query output + contract…

Author: zerodevblock-cyber

docs/standard-cli-contract-spec.md

@@ -50,7 +50,7 @@ The standard CLI has two distinct option layers:
 
 ### Global Options
 
-Global options affect the overall execution environment before the command is known.
+Global options affect the overall execution environment for the whole command run.
 
 Examples:
 
@@ -61,7 +61,9 @@ Examples:
 - quiet / verbose behavior
 - global help / version handling
 
-Global options are parsed by `GlobalOptions.parse(String[] args)`.
+Global options are parsed by `GlobalOptions.parse(String[] args)`. Execution modifiers may appear either before or
+after the command token. Top-level mode selectors are pre-command only, except for command-help handling described
+below.
 
 ### Command-Local Options
 
@@ -77,28 +79,28 @@ Command-local options are parsed by `CommandDefinition.parseArgs(String[] args)`
 
 ### Layer Boundary
 
-- global options configure how the CLI run is executed
+- global execution modifiers configure how the CLI run is executed
+- top-level mode selectors choose an alternate program mode before command execution
 - command-local options configure what the chosen command does
-- global parsing happens first
+- global parsing happens first and extracts known global options from the full argument list
 - command-local parsing happens only after the command token is known
 - a token must not be interpreted as both a global option and a command-local option in the same pass
 
 ## Contract 1: Global Option Parsing
 
-`GlobalOptions.parse(String[] args)` is responsible only for parsing options that affect the whole run before
-the command is known.
+`GlobalOptions.parse(String[] args)` is responsible only for parsing known options that affect the whole run.
 
 ### Parsing Model
 
-Global option parsing is a left-to-right first-pass scan.
+Global option parsing is a left-to-right first-pass scan across the full argument list.
 
 The parser consumes tokens until one of these happens:
 
-1. it reaches the first command token
-2. it reaches the end of input
-3. it encounters a malformed global option and fails with a usage error
+1. it reaches the end of input
+2. it encounters a malformed known global option and fails with a usage error
 
-This pass is intentionally narrow. It must not inspect or reinterpret command-local options.
+This pass is intentionally narrow. It extracts only known global options and must not reinterpret unknown
+post-command options that belong to command-local parsing.
 
 ### Supported Syntax
 
@@ -126,11 +128,15 @@ For Contract 1, this applies to valued global options only.
 
 ### Boundary Rules
 
-- Global options are only recognized before the command token.
+- Execution modifier global options are recognized before and after the command token.
+- Top-level mode selectors `--version` and `--interactive` are recognized only before the command token.
 - The first token before command resolution that does not begin with `-` is the command token.
 - The command token is normalized to lowercase for registry lookup.
-- After the command token is found, all remaining tokens are passed through unchanged as command arguments.
-- Tokens after the command token are never reinterpreted as global options, even if they look like global flags.
+- After the command token is found, execution modifier global options are extracted and all other tokens are passed
+  through unchanged as command arguments.
+- Unknown options after the command token are never reinterpreted as global options.
+- Post-command `--help` and `-h` are reserved for command help and are passed through as command arguments.
+- Post-command `--version` and `--interactive` are command-local tokens and are passed through as command arguments.
 
 Examples:
 
@@ -143,13 +149,29 @@ Examples:
   - command: `get-balance`
   - command args: `--address T...`
 - `wallet-cli get-balance --network nile`
+  - global options: `--network nile`
   - command: `get-balance`
-  - command args: `--network nile`
-  - `--network` is not treated as a global option because it appears after the command token
+  - command args: none
 - `wallet-cli get-balance --network=nile`
+  - global options: `--network=nile`
   - command: `get-balance`
-  - command args: `--network=nile`
-  - `--network=nile` is not treated as a global option because it appears after the command token
+  - command args: none
+- `wallet-cli get-balance --address T... --network nile`
+  - global options: `--network nile`
+  - command: `get-balance`
+  - command args: `--address T...`
+- `wallet-cli get-balance --help`
+  - command: `get-balance`
+  - command args: `--help`
+  - `--help` is not treated as global help because it appears after the command token
+- `wallet-cli get-balance --version`
+  - command: `get-balance`
+  - command args: `--version`
+  - `--version` is not treated as global version because it appears after the command token
+- `wallet-cli get-balance --interactive`
+  - command: `get-balance`
+  - command args: `--interactive`
+  - `--interactive` is not treated as global interactive mode because it appears after the command token
 
 ### No-Command Cases
 
@@ -196,7 +218,7 @@ The following are usage errors at the global parsing layer:
 - unknown global option before the command token
 - missing value for a valued global option
 - invalid value for a constrained global option
-- malformed global syntax before the command token
+- malformed syntax for a known global option
 
 Specific expectations:
 
@@ -216,6 +238,10 @@ Specific expectations:
   - usage error: missing or empty value for `--output`
 - `--quiet=true`
   - usage error: option `--quiet` does not take a value
+- `get-balance --network beta`
+  - usage error: invalid value for `--network`
+- `get-balance --unknown value`
+  - not a global parsing error; `--unknown value` remains command-local input
 
 Error classification for valued global options:
 

qa/contracts.tsv

@@ -12,7 +12,10 @@ contract__global_invalid_network_value_json|empty|none|default|json|usage|["--ou
 contract__global_flag_with_value_json|empty|none|default|json|usage|["--output","json","--quiet=true","current-network"]|||usage_error|||
 contract__global_repeated_network_json|empty|none|default|json|usage|["--output","json","--network","nile","--network","main","current-network"]|||usage_error|||
 contract__global_quiet_verbose_conflict_json|empty|none|default|json|usage|["--output","json","--quiet","--verbose","current-network"]|||usage_error|||
-contract__post_command_global_like_token_text|empty|none|default|text|usage|["current-network","--network","nile"]||||Unknown option: --network||
+contract__post_command_global_network_text|empty|none|default|text|success|["current-network","--network","nile"]||||Current network:||
+contract__post_command_unknown_option_text|empty|none|default|text|usage|["current-network","--unknown","value"]||||Unknown option: --unknown||
+contract__post_command_version_text|empty|none|default|text|usage|["current-network","--version"]||||Unknown option: --version||
+contract__post_command_interactive_text|empty|none|default|text|usage|["current-network","--interactive"]||||Unknown option: --interactive||
 contract__command_missing_required_value_text|empty|none|default|text|usage|["get-block-by-latest-num","--count"]||||Missing value for --count||
 contract__command_empty_required_value_json|empty|none|default|json|usage|["--output","json","get-block-by-latest-num","--count="]|||usage_error|||
 contract__command_boolean_flag_exec|empty|none|default|text|execution|["freeze-balance-v2","--amount","1","--multi"]|||execution_error|Error:||

src/main/java/org/tron/walletcli/Client.java

@@ -4798,11 +4798,9 @@ static boolean shouldLaunchInteractiveByDefault(String[] args, GlobalOptions glo
   }
 
   private static boolean requestsJsonOutput(String[] args) {
+    // Fallback scan for parse errors assumes --output is a standard-CLI global-only option.
     for (int i = 0; i < args.length; i++) {
       String token = args[i];
-      if (!token.startsWith("-")) {
-        return false;
-      }
       if ("--output".equals(token)) {
         return i + 1 < args.length && "json".equalsIgnoreCase(args[i + 1]);
       }

src/main/java/org/tron/walletcli/cli/GlobalOptions.java

@@ -1,6 +1,7 @@
 package org.tron.walletcli.cli;
 
-import java.util.Arrays;
+import java.util.ArrayList;
+import java.util.List;
 import java.util.Locale;
 
 public class GlobalOptions {
@@ -41,39 +42,61 @@ public static GlobalOptions parse(String[] args) {
         boolean networkSeen = false;
         boolean walletSeen = false;
         boolean grpcEndpointSeen = false;
+        List<String> commandArgs = new ArrayList<String>();
         for (int i = 0; i < args.length; i++) {
             String token = args[i];
+            boolean commandSeen = opts.command != null;
 
-            if (!token.startsWith("-")) {
+            if (!commandSeen && !token.startsWith("-")) {
                 opts.command = token.toLowerCase(Locale.ROOT);
-                opts.commandArgs = Arrays.copyOfRange(args, i + 1, args.length);
-                return opts;
+                continue;
             }
 
             if ("-h".equals(token)) {
-                opts.help = true;
+                if (commandSeen) {
+                    commandArgs.add(token);
+                } else {
+                    opts.help = true;
+                }
                 continue;
             }
 
-            if (token.startsWith("-h=")) {
+            if (!commandSeen && token.startsWith("-h=")) {
                 throw new CliUsageException("Option -h does not take a value");
             }
 
             if (!token.startsWith("--")) {
-                throw new CliUsageException("Unknown global option: " + token);
+                if (commandSeen) {
+                    commandArgs.add(token);
+                } else {
+                    throw new CliUsageException("Unknown global option: " + token);
+                }
+                continue;
             }
 
             ParsedLongOption parsed = parseLongOptionToken(token);
             switch (parsed.name) {
                 case "interactive":
+                    if (commandSeen) {
+                        commandArgs.add(token);
+                        break;
+                    }
                     ensureNoInlineValue(parsed, "--interactive");
                     opts.interactive = true;
                     break;
                 case "help":
+                    if (commandSeen) {
+                        commandArgs.add(token);
+                        break;
+                    }
                     ensureNoInlineValue(parsed, "--help");
                     opts.help = true;
                     break;
                 case "version":
+                    if (commandSeen) {
+                        commandArgs.add(token);
+                        break;
+                    }
                     ensureNoInlineValue(parsed, "--version");
                     opts.version = true;
                     break;
@@ -124,9 +147,14 @@ public static GlobalOptions parse(String[] args) {
                     }
                     break;
                 default:
-                    throw new CliUsageException("Unknown global option: --" + parsed.name);
+                    if (commandSeen) {
+                        commandArgs.add(token);
+                    } else {
+                        throw new CliUsageException("Unknown global option: --" + parsed.name);
+                    }
             }
         }
+        opts.commandArgs = commandArgs.toArray(new String[0]);
         return opts;
     }
 
@@ -154,6 +182,7 @@ private static String requireValue(String[] args, int optionIndex, ParsedLongOpt
         if (valueIndex >= args.length || args[valueIndex].startsWith("-")) {
             throw new CliUsageException("Missing value for " + optionName);
         }
+        // Valued globals intentionally consume the next non-flag token greedily; command names are not special here.
         return args[valueIndex];
     }