fix: harden cli help handling

Author: MaxLogic

.gitignore

@@ -84,3 +84,5 @@ modules/
 .agents/
 /bin/*.cmds
 /dist/
+*.log
+/issues/

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [v1.4] - 2026-06-21
+
+### Fixed
+
+- Added non-mutating `--help` and `/?` handling so help requests cannot fall through to file scanning.
+- Added CLI safety regression coverage to keep unknown options as non-mutating parse failures.
+
 ## [v1.3] - 2026-06-16
 
 ### Added

README.md

@@ -49,7 +49,7 @@ EncodingFixTool ext="*.pas,*.dpr, .dfm"
 
 | Param         | Aliases | Values                     | Default     | Meaning                                                                                        |
 | ------------- | ------- | -------------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
-| `help`        | `-h`    | —                          | —           | Prints extended help and exits.                                                                |
+| `help`        | `-h`, `--help`, `/?` | —              | —           | Prints extended help and exits without scanning or writing files.                               |
 | `dry`         | —       | —                          | off         | Dry run: analyze and report what **would** change; no writes.                                  |
 | `s`/`silent`  | —       | —                          | off         | No console output. (Overrides `verbose`.)                                                      |
 | `v`/`verbose` | —       | —                          | off         | More output: “OK” lines etc. (Ignored if `silent`.)                                            |
@@ -262,7 +262,7 @@ CLI arguments override preset values, so a one-off narrower run stays explicit:
 EncodingFixTool path=.\src preset=project-agent ext=pas,inc scope=git-changed format=json
 ```
 
-Invalid preset names, malformed JSON, and invalid preset option values fail before file rewriting starts.
+Invalid preset names, malformed JSON, invalid preset option values, and unknown command-line options fail before file rewriting starts.
 
 ## Related MaxLogic Delphi tooling
 

src/EncodingFixTool.dproj

@@ -90,19 +90,19 @@
         <SanitizedProjectName>EncodingFixTool</SanitizedProjectName>
         <VerInfo_IncludeVerInfo>true</VerInfo_IncludeVerInfo>
         <VerInfo_MajorVer>1</VerInfo_MajorVer>
-        <VerInfo_MinorVer>3</VerInfo_MinorVer>
+        <VerInfo_MinorVer>4</VerInfo_MinorVer>
         <VerInfo_Release>0</VerInfo_Release>
         <VerInfo_Build>0</VerInfo_Build>
         <VerInfo_Locale>1045</VerInfo_Locale>
-        <VerInfo_Keys>CompanyName=;FileDescription=;FileVersion=1.3.0.0;InternalName=;LegalCopyright=;LegalTrademarks=;OriginalFilename=;ProductName=;ProductVersion=1.3.0.0;Comments=;CFBundleName=</VerInfo_Keys>
+        <VerInfo_Keys>CompanyName=;FileDescription=;FileVersion=1.4.0.0;InternalName=;LegalCopyright=;LegalTrademarks=;OriginalFilename=;ProductName=;ProductVersion=1.4.0.0;Comments=;CFBundleName=</VerInfo_Keys>
         <DCC_Namespace>System;Xml;Data;Datasnap;Web;Soap;$(DCC_Namespace)</DCC_Namespace>
         <Icon_MainIcon>$(BDS)\bin\delphi_PROJECTICON.ico</Icon_MainIcon>
         <Icns_MainIcns>$(BDS)\bin\delphi_PROJECTICNS.icns</Icns_MainIcns>
         <DCC_ExeOutput>..\bin</DCC_ExeOutput>
         <CfgDependentOn>..\..\MaxLogicFoundation\MaxLogicDefault.optset</CfgDependentOn>
     </PropertyGroup>
     <PropertyGroup Condition="'$(Base_Android)'!=''">
-        <VerInfo_Keys>package=com.embarcadero.$(MSBuildProjectName);label=$(MSBuildProjectName);versionCode=1;versionName=1.3.0;persistent=False;restoreAnyVersion=False;installLocation=auto;largeHeap=False;theme=TitleBar;hardwareAccelerated=true;apiKey=;minSdkVersion=23;targetSdkVersion=34</VerInfo_Keys>
+        <VerInfo_Keys>package=com.embarcadero.$(MSBuildProjectName);label=$(MSBuildProjectName);versionCode=1;versionName=1.4.0;persistent=False;restoreAnyVersion=False;installLocation=auto;largeHeap=False;theme=TitleBar;hardwareAccelerated=true;apiKey=;minSdkVersion=23;targetSdkVersion=34</VerInfo_Keys>
         <BT_BuildType>Debug</BT_BuildType>
         <Android_LauncherIcon36>$(BDS)\bin\Artwork\Android\FM_LauncherIcon_36x36.png</Android_LauncherIcon36>
         <Android_LauncherIcon48>$(BDS)\bin\Artwork\Android\FM_LauncherIcon_48x48.png</Android_LauncherIcon48>
@@ -141,13 +141,13 @@
     <PropertyGroup Condition="'$(Base_Win32)'!=''">
         <DCC_Namespace>Winapi;System.Win;Data.Win;Datasnap.Win;Web.Win;Soap.Win;Xml.Win;Bde;$(DCC_Namespace)</DCC_Namespace>
         <BT_BuildType>Debug</BT_BuildType>
-        <VerInfo_Keys>CompanyName=;FileDescription=$(MSBuildProjectName);FileVersion=1.3.0.0;InternalName=;LegalCopyright=;LegalTrademarks=;OriginalFilename=;ProductName=$(MSBuildProjectName);ProductVersion=1.3.0.0;Comments=;ProgramID=com.embarcadero.$(MSBuildProjectName)</VerInfo_Keys>
+        <VerInfo_Keys>CompanyName=;FileDescription=$(MSBuildProjectName);FileVersion=1.4.0.0;InternalName=;LegalCopyright=;LegalTrademarks=;OriginalFilename=;ProductName=$(MSBuildProjectName);ProductVersion=1.4.0.0;Comments=;ProgramID=com.embarcadero.$(MSBuildProjectName)</VerInfo_Keys>
         <VerInfo_Locale>1033</VerInfo_Locale>
     </PropertyGroup>
     <PropertyGroup Condition="'$(Base_Win64)'!=''">
         <DCC_Namespace>Winapi;System.Win;Data.Win;Datasnap.Win;Web.Win;Soap.Win;Xml.Win;Bde;$(DCC_Namespace)</DCC_Namespace>
         <BT_BuildType>Debug</BT_BuildType>
-        <VerInfo_Keys>CompanyName=;FileDescription=$(MSBuildProjectName);FileVersion=1.3.0.0;InternalName=;LegalCopyright=;LegalTrademarks=;OriginalFilename=;ProductName=$(MSBuildProjectName);ProductVersion=1.3.0.0;Comments=;ProgramID=com.embarcadero.$(MSBuildProjectName)</VerInfo_Keys>
+        <VerInfo_Keys>CompanyName=;FileDescription=$(MSBuildProjectName);FileVersion=1.4.0.0;InternalName=;LegalCopyright=;LegalTrademarks=;OriginalFilename=;ProductName=$(MSBuildProjectName);ProductVersion=1.4.0.0;Comments=;ProgramID=com.embarcadero.$(MSBuildProjectName)</VerInfo_Keys>
         <VerInfo_Locale>1033</VerInfo_Locale>
     </PropertyGroup>
     <PropertyGroup Condition="'$(Cfg_1)'!=''">
@@ -177,7 +177,7 @@
     </PropertyGroup>
     <PropertyGroup Condition="'$(Cfg_2_Win32)'!=''">
         <VerInfo_Locale>1033</VerInfo_Locale>
-        <VerInfo_Keys>CompanyName=;FileDescription=$(MSBuildProjectName);FileVersion=1.3.0.0;InternalName=;LegalCopyright=;LegalTrademarks=;OriginalFilename=;ProductName=$(MSBuildProjectName);ProductVersion=1.3.0.0;Comments=;ProgramID=com.embarcadero.$(MSBuildProjectName)</VerInfo_Keys>
+        <VerInfo_Keys>CompanyName=;FileDescription=$(MSBuildProjectName);FileVersion=1.4.0.0;InternalName=;LegalCopyright=;LegalTrademarks=;OriginalFilename=;ProductName=$(MSBuildProjectName);ProductVersion=1.4.0.0;Comments=;ProgramID=com.embarcadero.$(MSBuildProjectName)</VerInfo_Keys>
         <Manifest_File>(None)</Manifest_File>
         <AppDPIAwarenessMode>none</AppDPIAwarenessMode>
     </PropertyGroup>

src/EncodingFixTool.res

@@ -1081,7 +1081,7 @@ function TEncodingFixTool.ShowHelp: integer;
     '  EncodingFixTool [params]' + sLineBreak +
     sLineBreak +
     'Params:' + sLineBreak +
-    '  help                  : Show this help text.' + sLineBreak +
+    '  help | -h | --help | /? : Show this help text.' + sLineBreak +
     '  dry                   : Dry run (no files are changed).' + sLineBreak +
     '  s | silent            : No console output.' + sLineBreak +
     '  v | verbose           : More output (not compatible with silent).' + sLineBreak +
@@ -1168,8 +1168,14 @@ function TEncodingFixTool.ParseCommandLine(out aOptions: TOptions): integer;
   begin
     p := Trim(ParamStr(aIndex));
 
-    if startsStr('-', p) {$IFDEF MsWindows}or StartsStr('/', p){$ENDIF} then
+    while (p <> '') and ((p[1] = '-') {$IFDEF MsWindows}or (p[1] = '/'){$ENDIF}) do
+    begin
       delete(p, 1, 1);
+    end;
+    if p = '?' then
+    begin
+      p := 'help';
+    end;
     if p = '' then
     begin
       aKey := '';

src/EncodingFixToolCore.pas

@@ -35,6 +35,35 @@ function Invoke-Tool {
 
 Assert-True (Test-Path -LiteralPath $ToolPath) "Tool not found: $ToolPath"
 
+$lSafetyRoot = Initialize-TestRoot
+try {
+  $lSafetyFile = Join-Path $lSafetyRoot 'sample.pas'
+  [System.IO.File]::WriteAllBytes(
+    $lSafetyFile,
+    [System.Text.Encoding]::ASCII.GetBytes("unit sample;`nend.")
+  )
+  $lOriginalBytes = [System.IO.File]::ReadAllBytes($lSafetyFile)
+
+  $lResult = Invoke-Tool @('--help')
+  Assert-True ($lResult.ExitCode -eq 0) "--help should show help and exit 0."
+  Assert-True ($lResult.Output -match 'Usage:') "--help output should include usage text."
+  Assert-True ([Convert]::ToBase64String($lOriginalBytes) -eq [Convert]::ToBase64String([System.IO.File]::ReadAllBytes($lSafetyFile))) "--help must not rewrite files."
+
+  $lResult = Invoke-Tool @('/?')
+  Assert-True ($lResult.ExitCode -eq 0) "/? should show help and exit 0."
+  Assert-True ($lResult.Output -match 'Usage:') "/? output should include usage text."
+  Assert-True ([Convert]::ToBase64String($lOriginalBytes) -eq [Convert]::ToBase64String([System.IO.File]::ReadAllBytes($lSafetyFile))) "/? must not rewrite files."
+
+  $lResult = Invoke-Tool @("path=$lSafetyRoot", '--definitely-not-valid')
+  Assert-True ($lResult.ExitCode -ne 0) "Unknown options should fail before scanning."
+  Assert-True ($lResult.Output -match 'ERROR: unknown parameter:') "Unknown options should explain the parse failure."
+  Assert-True ([Convert]::ToBase64String($lOriginalBytes) -eq [Convert]::ToBase64String([System.IO.File]::ReadAllBytes($lSafetyFile))) "Unknown options must not rewrite files."
+} finally {
+  if (Test-Path -LiteralPath $lSafetyRoot) {
+    Remove-Item -LiteralPath $lSafetyRoot -Recurse -Force
+  }
+}
+
 $lRoot = Initialize-TestRoot
 try {
   $lReadOnlyFile = Join-Path $lRoot 'readonly.pas'