Installer Script Encoding Automation: A Dash Character Was Silently Corrupting the Installer

A text file is, at the level bytes are actually stored, just a sequence of numbers — nothing in the file itself declares which character set those numbers are supposed to represent. A byte-order mark is a small, optional, invisible marker some encodings place at the very start of a file specifically to remove that ambiguity for whatever program opens it next. A file saved as UTF-8 WITHOUT that marker is, from the reading program's point of view, indistinguishable at the byte level from a file saved in an entirely different, older single-byte encoding for every character that happens to fall in the range both encodings share — which covers plain English letters, digits, and most punctuation, but not every accented letter or typographic dash. Two programs can each read the identical file, apply a different but individually reasonable guess about its encoding, and produce two different, both internally consistent, readings of the same bytes — with only one of them matching what the file's author actually typed.

Plain ASCII text — ordinary English letters, digits, and basic punctuation like a hyphen or a straight quote — happens to occupy the identical byte values across UTF-8 and the common legacy single-byte code pages that predate it, which is exactly why a script written entirely in that narrow character set can be saved without a byte-order mark and still behave identically under either interpretation, for years, without anyone noticing the ambiguity exists at all. The moment a script's author reaches for a character outside that narrow shared range — a longer, typographically distinct dash instead of a plain hyphen, a genuine curly quote instead of a straight one, an accented letter in a name — the two encodings diverge, and a file with no byte-order mark to resolve that divergence becomes genuinely ambiguous for the first time. The installer script had almost certainly worked correctly for a long time before this specific change, for the same reason most files like it do: nothing had yet been typed into it that actually exposed the gap.

Centriu Guardian's installer is packaged by a dedicated build script that assembles every file the setup process needs — agent binaries, configuration, and a handful of PowerShell scripts responsible for the installation logic itself — into a single distributable package. Before this fix, that packaging step copied each `.ps1` file into the package exactly as it existed on disk, byte for byte, with no attention paid to how the file had been encoded or whether a byte-order mark was present. Whatever ambiguity already existed in the source file simply carried forward unchanged into the shipped installer, to be resolved — correctly or not — by whichever PowerShell engine version happened to run it on an end user's own machine.

The fix inserts an explicit encoding-normalization step directly into the packaging process, applied to every `.ps1` file the installer package contains, with no exceptions carved out for any individual script. Each file is read back in as UTF-8 text — the correct, intended encoding all along, and the one every modern editor already assumes by default — and then written back out with an explicit UTF-8 byte-order mark prepended. That marker removes the ambiguity a plain UTF-8 file otherwise leaves behind: any PowerShell engine encountering it, including the older 5.1 engine that ships with Windows itself, now reads the file's actual bytes using the correct table, rather than falling back to a legacy guess that happens to diverge from UTF-8 for exactly the characters most likely to appear in ordinary, human-written text. The fix's own commit records a direct parse-check confirming all five of the installer's packaged scripts parse cleanly after the rewrite, and a full headless installation test — extracting the freshly rebuilt package and running the installer logic end to end — confirming the agent actually starts and reports itself healthy afterward, not merely that the script's syntax now parses without error.

Before the fix, one specific mark of punctuation in the installer's own script text — like a word replaced with a visually similar one during a careless translation — was silently read as a completely different mark by the exact tool actually running the script on a typical Windows machine, closing a sentence early and leaving the words after it to be misread as something else entirely, producing an error about a term nobody had actually written. After the fix, the script's own file explicitly states which alphabet it was written in, so the tool reading it never has to guess — and never again substitutes one mark for another.

Centriu Guardian's packaged installer scripts now carry an explicit encoding marker confirming they should be read as UTF-8, closing a gap where a missing marker had left Windows's own built-in PowerShell engine to guess — incorrectly, for specific punctuation characters — and silently corrupt the script's own text before ever reaching the point of executing it.

This automation covers specifically how Centriu Guardian's own installer PACKAGE is built and encoded before it reaches an end user's machine. It is a distinct concern from this pillar's separate pages on the installer's runtime behavior once it is already running correctly — how it detects an outdated locally-installed agent, or how it handles an elevated script that exceeds Windows's own command-line length limit — each of those covers a different stage of the same overall installation and update pipeline.

Leaving a text file's encoding unmarked and trusting whatever reads it next to guess correctly works, in practice, for as long as nobody writes a character outside the narrow range every common encoding happens to agree on — which can be a very long time for a script that started out using only plain ASCII punctuation. Declaring the encoding explicitly, with an actual marker at the start of the file, removes the guess entirely: every reader, regardless of its own default assumption or the specific engine version running it, arrives at the identical, correct interpretation of the exact same bytes.