fix(installer): stop it lying, stop it leaking, and make it findable

Nine fixes from a review of the installer against its actual audience: DT leads
at sister sites who are not Windows, IIS or Python specialists and who will lean
on an AI assistant to get through it.

TRUTHFULNESS. The preflight was advisory - an operator read 'IIS is not
installed', pressed Next, answered five more pages and the install died partway
through with Python already on the box. The results page now blocks while
anything is failing, repaints on every run instead of latching after the first,
and offers 'Check again' so a fixed problem does not mean starting over. On
failure the wizard said 'Nothing was left running', which is false in every path
because the stages run with -OnFailure never: it now says the server is
part-configured, that re-running is safe, and how to remove it. The final page no
longer reads 'ShopDB-Flask is ready' after a failed install.

SECRETS. The generated MySQL root password went to Write-Host in a process the
wizard runs hidden - so nobody saw it - and stdout is forwarded into the setup
log operators are told to send to support, so it was permanently recorded for
everyone who did not need it. It now goes to an ACL'd file. Database dumps, which
contain every user password hash, landed in a ProgramData directory readable by
every user on the box; the directory is now locked at creation.

UPGRADES ON REMOTE-DATABASE SITES. mysqldump was looked for only under local
MySQL install paths, so a site whose database is on another host silently skipped
every pre-upgrade backup - after stage 2 had already stopped the pool and
replaced the tree. Find-MysqlTool now prefers a client shipped in the bundle,
stage 2 stages it onto the server, preflight reports when it is missing, and
mysqlclient\ is an optional locked payload.

UNINSTALL. A subpath install is an IIS Application, not a site; removing only the
site left the application pointing at a deleted directory, so the parent site -
at West Jefferson, the live classic ASP - served 503 on that path forever while
Add/Remove Programs reported success. Uninstall now reads MOUNT_PATH and removes
the application. The firewall rule was created as "$SiteName $SitePort" and
removed as the literal 'ShopDB-Flask 8090', which matches nothing.

DAY-2 TOOLING. Every shortcut now passes -AppRoot and -SitePort, and the console
forwards them through its own elevation and 32-bit relaunches instead of
discarding them - a non-default directory or port made it report a healthy site
as broken, from a shortcut the installer wrote. 'Open ShopDB-Flask' resolved to a
hardcoded localhost:8090 that was wrong for every subpath install; it now asks
the console, which reads the address the installer recorded, and no longer
demands administrator to open a browser.

SMOKE TEST. The parent-site port lookup filtered for an http binding and
defaulted to 80, so an https-only parent site failed a working install with a red
dialog.

DOCS AND /api/docs. The installer was invisible: nothing in docs/, README.md or
CLAUDE.md mentioned it, so a DT lead or their assistant landed on the manual IIS
runbook and hand-built the very server the installer then refuses to upgrade.
docs/INSTALL-WINDOWS.md and docs/OPERATE-WINDOWS.md are now the canonical route,
the two manual runbooks are bannered as reference-only, README and CLAUDE.md
route by target, and llms.txt tells an assistant which document to follow and to
ask for 'check -Json' before diagnosing. Both ship on the server, along with
openapi.json and llms.txt - without those the self-hosted /api/docs was broken on
every installed box, which matters most to the sites least able to debug it.
Stage 5 now checks it actually serves.

shopdb-admin.ps1 gains 'check -Json': one structured, secret-free block covering
version, publishing method, IIS state, HTTP reachability, database, Python
version, plugins and errors. That is the cheapest useful answer to 'the operator
will ask an LLM' - it works with no infrastructure, which a install-time MCP
server could not.

deploy/windows/installer/ShopDBFlask.iss

@@ -93,7 +93,10 @@ Name: "english"; MessagesFile: "compiler:Default.isl"
 WelcomeLabel1=Set up ShopDB-Flask on this server
 ; Short, and says the two things an operator actually wants up front: it will not
 ; need the internet, and it will tell them before it changes anything.
-WelcomeLabel2=Everything needed is included in this installer. No internet connection is used at any point.%n%nYou will be asked four short questions, and nothing on this server is changed until you reach the final confirmation.%n%nThe next page checks that this server is ready. It only reads - it changes nothing.
+; The installer supplies Python, the wheels, the IIS modules and optionally MySQL.
+; It does NOT install the IIS Web Server role itself - that is a Windows feature,
+; and the check on the next page confirms it is present rather than adding it.
+WelcomeLabel2=Everything this application needs is included - Python, its packages, the IIS modules and optionally MySQL. No internet connection is used at any point.%n%nThis server must already have the IIS Web Server role installed. The next page checks that, and everything else this needs, before anything is changed.%n%nYou will then be asked a few short questions. Nothing on this server is changed until the final confirmation.
 ClickNext=Click Next to check this server.
 FinishedHeadingLabel=ShopDB-Flask is ready
 SetupAppTitle=ShopDB-Flask Setup
@@ -131,18 +134,28 @@ Source: "swatch-bad.bmp";  Flags: dontcopy
 
 [Icons]
 ; A folder rather than loose icons: this is a server tool, not a desktop app.
+;
+; EVERY shortcut passes -AppRoot and -SitePort. The console defaults to
+; C:\shopdb-flask and port 8090, so on any install that chose a different
+; directory or port it looked in the wrong place and reported a perfectly healthy
+; site as broken - from a Start Menu shortcut the installer wrote itself.
 Name: "{group}\ShopDB-Flask Console"; Filename: "powershell.exe"; \
-    Parameters: "-NoExit -NoProfile -ExecutionPolicy Bypass -File ""{app}\shopdb-admin.ps1"""; \
+    Parameters: "-NoExit -NoProfile -ExecutionPolicy Bypass -File ""{app}\shopdb-admin.ps1"" -AppRoot ""{app}"" -SitePort {code:SitePortValue}"; \
     WorkingDir: "{app}"; IconFilename: "{app}\shopdb.ico"; \
     Comment: "Status, restart, logs and backups"
-Name: "{group}\Open ShopDB-Flask"; Filename: "http://localhost:8090/login"; \
-    IconFilename: "{app}\shopdb.ico"; Comment: "Open the application in a browser"
+; Resolves the address from .env at click time rather than baking one in. The
+; literal http://localhost:8090/login this used to carry was wrong for every
+; subpath install and every non-default port, with no operator mistake involved.
+Name: "{group}\Open ShopDB-Flask"; Filename: "powershell.exe"; \
+    Parameters: "-NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File ""{app}\shopdb-admin.ps1"" open -AppRoot ""{app}"" -SitePort {code:SitePortValue}"; \
+    WorkingDir: "{app}"; IconFilename: "{app}\shopdb.ico"; \
+    Comment: "Open the application in a browser"
 Name: "{group}\Restart ShopDB-Flask"; Filename: "powershell.exe"; \
-    Parameters: "-NoProfile -ExecutionPolicy Bypass -File ""{app}\shopdb-admin.ps1"" restart"; \
+    Parameters: "-NoProfile -ExecutionPolicy Bypass -File ""{app}\shopdb-admin.ps1"" restart -AppRoot ""{app}"" -SitePort {code:SitePortValue}"; \
     WorkingDir: "{app}"; IconFilename: "{app}\shopdb.ico"; \
     Comment: "Recycle the application pool"
 Name: "{group}\Back up the database"; Filename: "powershell.exe"; \
-    Parameters: "-NoExit -NoProfile -ExecutionPolicy Bypass -File ""{app}\shopdb-admin.ps1"" backup"; \
+    Parameters: "-NoExit -NoProfile -ExecutionPolicy Bypass -File ""{app}\shopdb-admin.ps1"" backup -AppRoot ""{app}"" -SitePort {code:SitePortValue}"; \
     WorkingDir: "{app}"; IconFilename: "{app}\shopdb.ico"; \
     Comment: "Write a .sql dump to ProgramData"
 
@@ -155,7 +168,7 @@ Name: "{group}\Back up the database"; Filename: "powershell.exe"; \
 ; System32 from a 32-bit process. The script also self-corrects, but launching
 ; it correctly avoids a visible relaunch.
 Filename: "{win}\Sysnative\WindowsPowerShell\v1.0\powershell.exe"; \
-    Parameters: "-NoExit -NoProfile -ExecutionPolicy Bypass -File ""{app}\shopdb-admin.ps1"""; \
+    Parameters: "-NoExit -NoProfile -ExecutionPolicy Bypass -File ""{app}\shopdb-admin.ps1"" -AppRoot ""{app}"" -SitePort {code:SitePortValue}"; \
     Description: "Open the ShopDB-Flask console"; \
     Flags: postinstall skipifsilent unchecked
 
@@ -171,6 +184,12 @@ var
   BannerSub:      TNewStaticText;
   DetailPanel:    TPanel;
   FooterText:     TNewStaticText;
+  RecheckButton:  TNewButton;
+  // Set by the preflight render. The wizard REFUSES to leave the results page
+  // while this is True: the check used to be advisory, so a server missing IIS
+  // sailed through every page and failed in the middle of installing, having
+  // already put Python on the box.
+  PreflightBlocked: Boolean;
   PreflightDone:  Boolean;
   // Shown while the preflight runs. Without it, clicking Next appears to hang:
   // the check takes a few seconds, runs hidden, and gives no sign of life.
@@ -268,6 +287,11 @@ begin
   Result.Bitmap.LoadFromFile(ExpandConstant('{tmp}\') + Swatch);
 end;
 
+// Defined further down, next to the preflight rendering they drive. Declared here
+// because InitializeWizard wires RecheckClick to a button before that point.
+procedure RunPreflight; forward;
+procedure RecheckClick(Sender: TObject); forward;
+
 procedure InitializeWizard;
 var
   I: Integer;
@@ -324,10 +348,22 @@ begin
   FooterText.Parent := PreflightPage.Surface;
   FooterText.Left := 0;
   FooterText.Top := PreflightPage.SurfaceHeight - ScaleY(16);
-  FooterText.Width := PreflightPage.SurfaceWidth;
+  FooterText.Width := PreflightPage.SurfaceWidth - ScaleX(84);
   FooterText.AutoSize := False;
   FooterText.Caption := '';
 
+  // A blocking page needs a way forward that is not "cancel the installer". The
+  // operator fixes what the page told them to fix - installs the IIS role, frees
+  // the port - and re-checks without starting over.
+  RecheckButton := TNewButton.Create(WizardForm);
+  RecheckButton.Parent := PreflightPage.Surface;
+  RecheckButton.Width := ScaleX(78);
+  RecheckButton.Height := ScaleY(23);
+  RecheckButton.Left := PreflightPage.SurfaceWidth - RecheckButton.Width;
+  RecheckButton.Top := PreflightPage.SurfaceHeight - ScaleY(23);
+  RecheckButton.Caption := 'Check again';
+  RecheckButton.OnClick := @RecheckClick;
+
   CheckingPage := CreateOutputProgressPage('Checking this server',
     'Reading the current configuration. Nothing is being changed.');
 
@@ -664,6 +700,94 @@ begin
     FooterText.Caption := IntToStr(Passes) + ' checks passed. Nothing has been changed on this server.';
 end;
 
+// Run the read-only check and paint its results. Called from Next on the welcome
+// page, and again whenever the operator fixes something and presses Check again.
+//
+// Stage 1 changes nothing, so running it before the operator commits to anything
+// is free, and it catches the blockers that are expensive later: IIS absent,
+// locked config sections, the port in use, MySQL 5.6 missing its index flags.
+procedure RunPreflight;
+var
+  I, ResultCode: Integer;
+  Output: TExecOutput;
+  PreflightScript, Detail: String;
+  HasBlockers: Boolean;
+begin
+  // The bundle is NOT extracted yet at wizard time - [Files] is processed during
+  // the install step. Pull just this one script out of the compressed payload.
+  ExtractTemporaryFile('shopdb-preflight.ps1');
+  PreflightScript := ExpandConstant('{tmp}\shopdb-preflight.ps1');
+
+  // Visible feedback for the few seconds the check takes. SW_HIDE means the
+  // operator sees nothing at all otherwise, and a frozen wizard reads as a
+  // crash. ProgressBar.Style := npbstMarquee because the duration is unknown -
+  // a bar that sits at 0% is worse than no bar.
+  CheckingPage.SetText('Looking at IIS, disk, ports and the database...', '');
+  CheckingPage.SetProgress(0, 0);
+  CheckingPage.ProgressBar.Style := npbstMarquee;
+  CheckingPage.Show;
+  try
+    // ExecAndCaptureOutput (6.4.0+) hands back stdout and stderr as string arrays,
+    // so output never touches disk. That deletes BOTH bugs this page shipped with:
+    //   - Exec() has no shell, so "> file" went to PowerShell as a literal
+    //     argument and no file was ever written (page came up empty);
+    //   - PowerShell 5.1 writes UTF-16LE, and LoadStringFromFile reads bytes as
+    //     ANSI, so the page rendered as garbage with a null between characters.
+    // Neither failure mode can recur now: there is no file and no encoding step.
+    // 64-bit PowerShell - see PowerShellPath. The IIS checks fail without it.
+    ExecAndCaptureOutput(PowerShellPath,
+         '-NoProfile -ExecutionPolicy Bypass -File "' + PreflightScript + '" -Delimited',
+         '', SW_HIDE, ewWaitUntilTerminated, ResultCode, Output);
+
+    // Every run repaints from scratch. The old code rendered ONCE and latched,
+    // so a re-check could not have shown a different answer even if the operator
+    // had fixed everything.
+    while DetailPanel.ControlCount > 0 do
+      DetailPanel.Controls[0].Free;
+
+    PreflightDone := True;
+    if (not Output.Error) and (GetArrayLength(Output.StdOut) > 0) then
+    begin
+      RenderPreflight(Output.StdOut, HasBlockers);
+      PreflightBlocked := HasBlockers;
+    end
+    else
+    begin
+      // stderr is captured SEPARATELY, so a failure can report what actually
+      // went wrong instead of only an exit code.
+      Detail := '';
+      for I := 0 to GetArrayLength(Output.StdErr) - 1 do
+        Detail := Detail + Output.StdErr[I] + ' ';
+      if Trim(Detail) = '' then Detail := 'No error output was produced.';
+      SetSwatch(BannerBar, 'swatch-warn.bmp');
+      BannerText.Caption := 'Could not check this server';
+      BannerSub.Caption := 'Nothing has been verified. Continuing is a risk.';
+      AddRow(ScaleY(4), 'swatch-warn.bmp',
+             'Check did not run (exit ' + IntToStr(ResultCode) + ')', Detail);
+      FooterText.Caption := 'Nothing has been changed on this server.';
+      // A check that could not RUN is not a check that PASSED. It does not block -
+      // there is no evidence of a problem - but it must not read like a green light.
+      PreflightBlocked := False;
+    end;
+  finally
+    CheckingPage.Hide;
+  end;
+end;
+
+procedure RecheckClick(Sender: TObject);
+begin
+  RunPreflight;
+end;
+
+// The port the operator chose, for the [Icons]/[Run] entries. A subpath install
+// is reached on the parent site's port, and the console works that out from
+// MOUNT_PATH in .env, so the value only has to be right for the own-site case.
+function SitePortValue(Param: String): String;
+begin
+  Result := SitePage.Values[1];
+  if Trim(Result) = '' then Result := '8090';
+end;
+
 // Where an EXISTING install would be, for the pre-fill reads.
 //
 // Not WizardDirValue() alone: these pages are inserted after wpWelcome and so
@@ -681,75 +805,26 @@ begin
 end;
 
 function NextButtonClick(CurPageID: Integer): Boolean;
-var
-  ResultCode, I: Integer;
-  Output: TExecOutput;
-  PreflightScript, Detail: String;
-  HasBlockers: Boolean;
 begin
   Result := True;
 
   if CurPageID = wpWelcome then
+    RunPreflight;
+
+  // The results page BLOCKS while anything is failing. It used to be advisory:
+  // the operator read "IIS is not installed", pressed Next, answered five more
+  // pages, and the install then died partway through with Python already on the
+  // box. Refusing here costs them nothing - the server is untouched at this
+  // point - and the page already says what to do about each failure.
+  if CurPageID = PreflightPage.ID then
   begin
-    // Stage 1 is read-only, so running it before the operator commits to
-    // anything is free and catches the common blockers (IIS absent, locked
-    // config sections, port in use, MySQL 5.6 missing its index flags).
-    // The bundle is NOT extracted yet at wizard time - [Files] is processed during
-    // the install step. Pull just this one script out of the compressed payload.
-    ExtractTemporaryFile('shopdb-preflight.ps1');
-    PreflightScript := ExpandConstant('{tmp}\shopdb-preflight.ps1');
-
-    // Visible feedback for the few seconds the check takes. SW_HIDE means the
-    // operator sees nothing at all otherwise, and a frozen wizard reads as a
-    // crash. ProgressBar.Style := npbstMarquee because the duration is unknown -
-    // a bar that sits at 0% is worse than no bar.
-    CheckingPage.SetText('Looking at IIS, disk, ports and the database...', '');
-    CheckingPage.SetProgress(0, 0);
-    CheckingPage.ProgressBar.Style := npbstMarquee;
-    CheckingPage.Show;
-    try
-
-    // ExecAndCaptureOutput (6.4.0+) hands back stdout and stderr as string arrays,
-    // so output never touches disk. That deletes BOTH bugs this page shipped with:
-    //   - Exec() has no shell, so "> file" went to PowerShell as a literal
-    //     argument and no file was ever written (page came up empty);
-    //   - PowerShell 5.1 writes UTF-16LE, and LoadStringFromFile reads bytes as
-    //     ANSI, so the page rendered as garbage with a null between characters.
-    // Neither failure mode can recur now: there is no file and no encoding step.
-    // 64-bit PowerShell - see PowerShellPath. The IIS checks fail without it.
-    ExecAndCaptureOutput(PowerShellPath,
-         '-NoProfile -ExecutionPolicy Bypass -File "' + PreflightScript + '" -Delimited',
-         '', SW_HIDE, ewWaitUntilTerminated, ResultCode, Output);
-    // Build the rows once. Going Back and Next again must not stack a second set
-    // of controls on top of the first.
-    if not PreflightDone then
+    if PreflightBlocked then
     begin
-      PreflightDone := True;
-      if (not Output.Error) and (GetArrayLength(Output.StdOut) > 0) then
-      begin
-        RenderPreflight(Output.StdOut, HasBlockers);
-        if HasBlockers then
-          MsgBox('This server is not ready. The problems are listed on the next '
-                 + 'page, each with what to do about it.', mbError, MB_OK);
-      end
-      else
-      begin
-        // stderr is captured SEPARATELY, so a failure can report what actually
-        // went wrong instead of only an exit code.
-        Detail := '';
-        for I := 0 to GetArrayLength(Output.StdErr) - 1 do
-          Detail := Detail + Output.StdErr[I] + ' ';
-        if Trim(Detail) = '' then Detail := 'No error output was produced.';
-        SetSwatch(BannerBar, 'swatch-warn.bmp');
-        BannerText.Caption := 'Could not check this server';
-        BannerSub.Caption := 'Installation can continue, but nothing has been verified.';
-        AddRow(ScaleY(4), 'swatch-warn.bmp',
-               'Check did not run (exit ' + IntToStr(ResultCode) + ')', Detail);
-        FooterText.Caption := 'Nothing has been changed on this server.';
-      end;
-    end;
-    finally
-      CheckingPage.Hide;
+      MsgBox('This server is not ready yet.' + #13#10#13#10
+             + 'Each problem above says what to do about it. Fix them, then choose '
+             + '"Check again".' + #13#10#13#10
+             + 'Nothing has been changed on this server.', mbError, MB_OK);
+      Result := False;
     end;
   end;
 
@@ -992,8 +1067,19 @@ begin
     else
       Result := 'The installation could not be completed (exit '
                 + IntToStr(ResultCode) + ').';
+    // NOT "nothing was left running". The stages run with -OnFailure never, so
+    // nothing is rolled back: whatever had been created by the failing point is
+    // still there. Claiming otherwise sent operators away believing the server
+    // was clean when it was half-configured, and the next thing they did was
+    // install again on top of it.
     Result := Result + #13#10#13#10
-              + 'Nothing was left running. Full details are in:' + #13#10
+              + 'This server has been part-configured. Whatever had been done '
+              + 'before the failure is still in place.' + #13#10#13#10
+              + 'What to do:' + #13#10
+              + '  - Fix the cause above, then run this installer again. Re-running '
+              + 'is safe and picks up where it left off.' + #13#10
+              + '  - Or remove it entirely from Settings > Apps.' + #13#10#13#10
+              + 'Full details, including everything that was created, are in:' + #13#10
               + ExpandConstant('{log}');
   end;
 end;
@@ -1021,14 +1107,36 @@ begin
     // "Unknown preprocessor directive" before Pascal parsing happens. Keep the
     // concatenation operator at the start of continuation lines instead.
     if Failure <> '' then
-      MsgBox(Failure, mbCriticalError, MB_OK)
+    begin
+      MsgBox(Failure, mbCriticalError, MB_OK);
+      // The final page is headed "ShopDB-Flask is ready" from [Messages]. After a
+      // failed install that is the last thing the operator reads, and it
+      // contradicts the error box they just dismissed. Setup cannot be made to
+      // fail from here, so at least stop it claiming success.
+      WizardForm.FinishedHeadingLabel.Caption := 'ShopDB-Flask is NOT installed';
+      WizardForm.FinishedLabel.Caption :=
+        'The installation did not complete. This server has been part-configured.'
+        + #13#10#13#10
+        + 'Fix the problem reported above and run this installer again - re-running '
+        + 'is safe. Or remove it from Settings > Apps.'
+        + #13#10#13#10
+        + 'The log is at ' + ExpandConstant('{log}');
+    end
     else
+    begin
+      // Recorded so the Start Menu shortcut and the console open the address this
+      // install actually serves, rather than a compile-time guess.
+      SaveStringToFile(ExpandConstant('{app}\.installed-url'), FinalUrl, False);
       MsgBox('ShopDB-Flask is installed.' + #13#10#13#10
              + 'Open  ' + FinalUrl
              + #13#10#13#10
              + 'With no user in the database that page offers to create the first '
-             + 'administrator and then runs the setup wizard.',
+             + 'administrator and then runs the setup wizard.'
+             + #13#10#13#10
+             + 'Day-to-day: use the ShopDB-Flask Console in the Start Menu, or read '
+             + ExpandConstant('{app}\docs\OPERATE-WINDOWS.md'),
              mbInformation, MB_OK);
+    end;
   end;
 end;