From 86b478e609a5d95866b50b938726647b6287d059 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Richard=20Sol=C3=A1r?= <solar.richard@gmail.com>
Date: Mon, 9 Nov 2026 14:35:37 +0100
Subject: [PATCH] fix: align uppercase short flags in help output

The continuation-line indent check in `pushFlags()` was case-sensitive, so
flags with an uppercase short form (`-H`, `-X`) were treated as having no
short form and got four extra spaces.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docs/reference.md                             |  4 +--
 src/lib/command-framework/help/CommandHelp.ts |  2 +-
 test/local/lib/command-framework/help.test.ts | 25 +++++++++++++++++++
 3 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/docs/reference.md b/docs/reference.md
index 420618be4..c58dae1ae 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -78,14 +78,14 @@ FLAGS
                           Leading slashes and a version prefix in the path are
                           optional. For example, "actor-runs/{runId}" and
                           "/v2/actor-runs/{runId}" are both accepted.
-      -H, --header=<value>    Additional HTTP header(s). Pass a
+  -H, --header=<value>    Additional HTTP header(s). Pass a
                           single "key:value" string, or a JSON object like
                           '{"X-Foo": "bar", "X-Baz": "qux"}' to send multiple
                           headers. The flag can only be used once; use the JSON form
                           for multiple headers.
   -l, --list-endpoints    List all available Apify API
                           endpoints.
-      -X, --method=<option>   The HTTP method to use. Defaults
+  -X, --method=<option>   The HTTP method to use. Defaults
                           to GET.
                           <options: GET|POST|PUT|PATCH|DELETE>
   -p, --params=<value>    Query parameters as a JSON object,
diff --git a/src/lib/command-framework/help/CommandHelp.ts b/src/lib/command-framework/help/CommandHelp.ts
index fa670f5aa..f17f7907f 100644
--- a/src/lib/command-framework/help/CommandHelp.ts
+++ b/src/lib/command-framework/help/CommandHelp.ts
@@ -321,7 +321,7 @@ export class CommandHelp extends BaseCommandRenderer {
 				.split('\n')
 				.map((line) => {
 					// For lines that don't start with a short flag, add 4 spaces to indent them further, and align with the flags that also have a short form
-					if (!/^-[a-z]/.test(line.trim())) {
+					if (!/^-[a-z]/i.test(line.trim())) {
 						return `    ${line}`;
 					}
 
diff --git a/test/local/lib/command-framework/help.test.ts b/test/local/lib/command-framework/help.test.ts
index 778f407b4..3fd05fde2 100644
--- a/test/local/lib/command-framework/help.test.ts
+++ b/test/local/lib/command-framework/help.test.ts
@@ -6,6 +6,7 @@ import {
 	type BuiltApifyCommand as _BuiltApifyCommand,
 	commandRegistry,
 } from '../../../../src/lib/command-framework/apify-command.js';
+import { Flags } from '../../../../src/lib/command-framework/flags.js';
 import {
 	registerCommandForHelpGeneration,
 	renderHelpForCommand,
@@ -63,6 +64,17 @@ class FakeActorPushData extends BuiltApifyCommand {
 	];
 }
 
+class FakeMixedFlags extends BuiltApifyCommand {
+	static override name = 'mixed-flags' as const;
+	static override description = 'A command with lowercase, uppercase and long-only flags.';
+	static override flags = {
+		body: Flags.string({ char: 'd', description: 'The request body.' }),
+		header: Flags.string({ char: 'H', description: 'Additional HTTP header(s).' }),
+		method: Flags.string({ char: 'X', description: 'The HTTP method to use.' }),
+		profile: Flags.string({ description: 'The stored account to use for this command.' }),
+	};
+}
+
 class FakeUtility extends BuiltApifyCommand {
 	static override name = 'utility' as const;
 	static override description = 'A utility command.';
@@ -132,6 +144,19 @@ describe('Help rendering', () => {
 			expect(output).toContain('Pass --template to skip the prompt.');
 		});
 
+		test('aligns short flags of any case in the same column', () => {
+			registerCommandForHelpGeneration('apify', FakeMixedFlags);
+			const output = stripAnsi(renderHelpForCommand(FakeMixedFlags));
+
+			const flagLines = output.split('\n').filter((line) => /^\s+(-\w, )?--/.test(line));
+			const shortFlagColumns = flagLines.filter((line) => /^\s+-\w, --/.test(line)).map((line) => line.indexOf('-'));
+			const longFlagColumns = flagLines.map((line) => line.indexOf('--'));
+
+			expect(shortFlagColumns).toHaveLength(3);
+			expect(new Set(shortFlagColumns).size).toBe(1);
+			expect(new Set(longFlagColumns).size).toBe(1);
+		});
+
 		test('renders example descriptions as shell-style # comments', () => {
 			registerCommandForHelpGeneration('apify', FakeRunsAbort);
 			const output = stripAnsi(renderHelpForCommand(FakeRunsAbort));