prismcast 1.9.0 → 1.10.0

package/dist/service/generators.js

@@ -1,120 +1,163 @@
-import { SERVICE_ID, SERVICE_NAME, getLogsDirectory, getNodeExecutablePath, getPlatform, getPrismCastEntryPoint, getPrismCastWorkingDirectory, getServiceFileDirectory, getServiceFilePath } from "../utils/platform.js";
-import { execFileSync, execSync } from "node:child_process";
-import fs from "node:fs";
-import path from "node:path";
-const { promises: fsPromises } = fs;
-/* Generates a launchd property list (plist) file for macOS. The plist is installed to ~/Library/LaunchAgents/ and configured with:
- * - RunAtLoad: Start when user logs in
- * - KeepAlive: Restart automatically if the process exits
- * - StandardOutPath/StandardErrorPath: Capture stdout/stderr to the data directory
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * generators.ts: Platform-specific service file generators for PrismCast.
+ *
+ * Each generator factory is a pure orchestrator over a GeneratorIO. The default I/O wiring lives in generators.context.ts; production callers go through
+ * getServiceGenerator() which uses createDefaultGeneratorIO() under the hood. Tests construct GeneratorIO literals inline so install/uninstall/start/stop run
+ * against fakes that record subprocess invocations and file writes without spawning real launchctl/systemctl/powershell.exe.
  */
+import { SERVICE_ID, SERVICE_NAME, getLogsDirectory, getNodeExecutablePath, getPrismCastEntryPoint, getPrismCastWorkingDirectory } from "../utils/platform.js";
+import { CONFIG_METADATA } from "../config/userConfig.js";
+import { createDefaultGeneratorIO } from "./generators.context.js";
+import path from "node:path";
 /**
- * Escapes a string for use in XML by replacing special characters with entities.
+ * Escapes a string for use in XML by replacing special characters with entities. Used by the macOS plist generator; the other platforms do not emit XML.
  * @param str - The string to escape.
  * @returns The escaped string safe for XML.
  */
 function escapeXml(str) {
     return str.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
 }
+/**
+ * Runs an asynchronous child_process call and, on failure, re-throws an Error whose message includes the trimmed stderr text captured from the failed child and
+ * whose cause chain points back at the original Error. Without the stderr enrichment, execFile/exec failures surface to users as a generic "Command failed: ..."
+ * line while the actual diagnostic - written by the child to stderr - is left on the Error's unread stderr Buffer. Attaching the original via Error.cause
+ * preserves the original stack and structured properties (status, signal, stdout, stderr) for any programmatic consumer.
+ * @param description - A short human-readable label describing what was attempted; prepended to the error message.
+ * @param run - The child_process thunk to execute.
+ */
+async function runAndSurfaceStderr(description, run) {
+    try {
+        await run();
+    }
+    catch (error) {
+        if (!(error instanceof Error)) {
+            throw error;
+        }
+        const raw = error.stderr;
+        const detail = (Buffer.isBuffer(raw) ? raw.toString("utf8") : ((typeof raw === "string") ? raw : "")).trim();
+        throw new Error(description + ": " + ((detail.length > 0) ? detail : error.message), { cause: error });
+    }
+}
+/**
+ * Returns the service definition's environment variables as a deterministically ordered array of [key, value] entries. Consumed by every generator to produce
+ * byte-stable output across regenerations (essential for reliable stale-path detection and clean diffs when users inspect the generated files).
+ * @param envVars - The environment variable map to order.
+ * @returns The entries sorted alphabetically by key.
+ */
+function sortedEnvEntries(envVars) {
+    return Object.entries(envVars).toSorted(([a], [b]) => a.localeCompare(b));
+}
+/**
+ * Checks whether a file exists using the async fs API via the supplied IO. Replaces fs.existsSync in async method bodies so the Promise<boolean> return type is
+ * backed by real I/O rather than a synchronous call papered over with an eslint-disable comment.
+ * @param io - The generator I/O context.
+ * @param filePath - The absolute path to check.
+ * @returns True if the file exists and is accessible, false otherwise.
+ */
+async function fileExists(io, filePath) {
+    try {
+        await io.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/* Generates a launchd property list (plist) file for macOS. The plist is installed to ~/Library/LaunchAgents/ and configured with:
+ * - RunAtLoad: Start when user logs in.
+ * - KeepAlive: Restart automatically if the process exits.
+ * - StandardOutPath/StandardErrorPath: Capture stdout/stderr to the data directory.
+ */
 /**
  * Creates a launchd service generator for macOS.
+ * @param io - The generator I/O context.
  * @returns A ServiceGenerator for launchd.
  */
-function createLaunchdGenerator() {
+function createLaunchdGenerator(io) {
+    /**
+     * Builds the plist XML from a service definition.
+     * @param definition - The service definition to serialize.
+     * @returns The plist content as a UTF-8 string.
+     */
+    function generatePlist(definition) {
+        const envEntries = sortedEnvEntries(definition.envVars)
+            .map(([key, value]) => ["      <key>" + escapeXml(key) + "</key>", "      <string>" + escapeXml(value) + "</string>"].join("\n"))
+            .join("\n");
+        return [
+            "<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
+            "<!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">",
+            "<plist version=\"1.0\">",
+            "<dict>",
+            "  <key>Label</key>",
+            "  <string>" + escapeXml(SERVICE_ID) + "</string>",
+            "",
+            "  <key>ProgramArguments</key>",
+            "  <array>",
+            "    <string>" + escapeXml(definition.nodePath) + "</string>",
+            "    <string>" + escapeXml(definition.entryPoint) + "</string>",
+            "  </array>",
+            "",
+            "  <key>WorkingDirectory</key>",
+            "  <string>" + escapeXml(definition.workingDir) + "</string>",
+            "",
+            "  <key>EnvironmentVariables</key>",
+            "  <dict>",
+            envEntries,
+            "  </dict>",
+            "",
+            "  <key>RunAtLoad</key>",
+            "  <true/>",
+            "",
+            "  <key>KeepAlive</key>",
+            "  <true/>",
+            "",
+            "  <key>StandardOutPath</key>",
+            "  <string>" + escapeXml(path.join(definition.logsDir, "service-stdout.log")) + "</string>",
+            "",
+            "  <key>StandardErrorPath</key>",
+            "  <string>" + escapeXml(path.join(definition.logsDir, "service-stderr.log")) + "</string>",
+            "</dict>",
+            "</plist>",
+            ""
+        ].join("\n");
+    }
     return {
-        generate(options) {
-            const nodePath = getNodeExecutablePath();
-            const entryPoint = getPrismCastEntryPoint();
-            const workingDir = getPrismCastWorkingDirectory();
-            const logsDir = getLogsDirectory();
-            // Build environment variables section. Always include PRISMCAST_SERVICE=1 for service detection.
-            const envVars = { PRISMCAST_SERVICE: "1", ...options.envVars };
-            // Generate the environment dictionary entries.
-            const envEntries = Object.entries(envVars)
-                .sort(([a], [b]) => a.localeCompare(b))
-                .map(([key, value]) => [
-                "      <key>" + escapeXml(key) + "</key>",
-                "      <string>" + escapeXml(value) + "</string>"
-            ].join("\n"))
-                .join("\n");
-            // Generate the plist content.
-            return [
-                "<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
-                "<!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">",
-                "<plist version=\"1.0\">",
-                "<dict>",
-                "  <key>Label</key>",
-                "  <string>" + escapeXml(SERVICE_ID) + "</string>",
-                "",
-                "  <key>ProgramArguments</key>",
-                "  <array>",
-                "    <string>" + escapeXml(nodePath) + "</string>",
-                "    <string>" + escapeXml(entryPoint) + "</string>",
-                "  </array>",
-                "",
-                "  <key>WorkingDirectory</key>",
-                "  <string>" + escapeXml(workingDir) + "</string>",
-                "",
-                "  <key>EnvironmentVariables</key>",
-                "  <dict>",
-                envEntries,
-                "  </dict>",
-                "",
-                "  <key>RunAtLoad</key>",
-                "  <true/>",
-                "",
-                "  <key>KeepAlive</key>",
-                "  <true/>",
-                "",
-                "  <key>StandardOutPath</key>",
-                "  <string>" + escapeXml(logsDir + "/service-stdout.log") + "</string>",
-                "",
-                "  <key>StandardErrorPath</key>",
-                "  <string>" + escapeXml(logsDir + "/service-stderr.log") + "</string>",
-                "</dict>",
-                "</plist>",
-                ""
-            ].join("\n");
-        },
-        getInstallPath() {
-            return getServiceFilePath();
-        },
-        async install(content) {
-            const installPath = this.getInstallPath();
-            const installDir = getServiceFileDirectory();
-            const logsDir = getLogsDirectory();
+        async install(definition) {
+            const installPath = io.getServiceFilePath();
+            const installDir = io.getServiceFileDirectory();
             // Ensure directories exist.
-            await fsPromises.mkdir(installDir, { recursive: true });
-            await fsPromises.mkdir(logsDir, { recursive: true });
-            // Write the plist file.
-            await fsPromises.writeFile(installPath, content, "utf8");
-            // Load the service with launchctl.
+            await io.mkdir(installDir, { recursive: true });
+            await io.mkdir(definition.logsDir, { recursive: true });
+            // Write the plist.
+            await io.writeFile(installPath, generatePlist(definition));
+            // Load the service with launchctl. If load fails because the definition is already loaded (common on reinstall), unload first then reload.
             try {
-                execSync("launchctl load -w \"" + installPath + "\"", { stdio: "pipe" });
+                await io.execFile("launchctl", ["load", "-w", installPath]);
             }
             catch {
-                // If load fails, try to unload first then reload (handles reinstall case).
                 try {
-                    execSync("launchctl unload \"" + installPath + "\"", { stdio: "pipe" });
+                    await io.execFile("launchctl", ["unload", installPath]);
                 }
                 catch {
                     // Ignore unload errors.
                 }
-                execSync("launchctl load -w \"" + installPath + "\"", { stdio: "pipe" });
+                await runAndSurfaceStderr("launchctl load failed", async () => io.execFile("launchctl", ["load", "-w", installPath]));
             }
         },
-        // eslint-disable-next-line @typescript-eslint/require-await
         async isInstalled() {
-            return fs.existsSync(this.getInstallPath());
+            return fileExists(io, io.getServiceFilePath());
         },
-        // eslint-disable-next-line @typescript-eslint/require-await
         async isRunning() {
             try {
-                // Use launchctl list | grep to get tab-separated output: "PID\tStatus\tLabel". The grep exits non-zero if not found.
-                const result = execSync("launchctl list | grep " + SERVICE_ID, { encoding: "utf8", stdio: "pipe" });
-                // Parse the PID from the first column. Format: "12345\t0\tcom.github.hjdhjd.prismcast" or "-\t0\t..." if loaded but not running.
-                const pid = result.trim().split("\t")[0];
-                // PID is "-" when loaded but process not running, or a number when actually running.
+                // launchctl list emits tab-separated rows: "PID\tStatus\tLabel". We find the row for this service and parse the PID from the first column. A PID of "-"
+                // means the service is loaded but not actively running.
+                const { stdout } = await io.execFile("launchctl", ["list"]);
+                const line = stdout.split("\n").find((row) => row.includes(SERVICE_ID));
+                if (!line) {
+                    return false;
+                }
+                const pid = line.trim().split("\t")[0];
                 return (pid !== "-") && !isNaN(Number(pid));
             }
             catch {
@@ -123,111 +166,102 @@ function createLaunchdGenerator() {
         },
         platform: "darwin",
         serviceManager: "launchd",
-        // eslint-disable-next-line @typescript-eslint/require-await
         async start() {
-            const installPath = this.getInstallPath();
-            // Unload first to clear any stale loaded-but-not-running state. Without this, `launchctl load -w` is a no-op when the definition is already loaded
-            // (e.g., after a crash or upgrade with changed paths), and the cached stale definition is reused.
+            const installPath = io.getServiceFilePath();
+            // Unload first to clear any stale loaded-but-not-running state. Without this, `launchctl load -w` is a no-op when the definition is already loaded (e.g.,
+            // after a crash or upgrade with changed paths), and the cached stale definition is reused.
             try {
-                execSync("launchctl unload \"" + installPath + "\"", { stdio: "pipe" });
+                await io.execFile("launchctl", ["unload", installPath]);
             }
             catch {
-                // Ignore — may not be loaded.
+                // Ignore - may not be loaded.
             }
-            // Load the plist with the current (possibly updated) definition.
-            execSync("launchctl load -w \"" + installPath + "\"", { stdio: "pipe" });
-            // Explicitly start the service. This handles the case where RunAtLoad doesn't trigger (e.g., load-then-start sequence).
-            execSync("launchctl start " + SERVICE_ID, { stdio: "pipe" });
+            await runAndSurfaceStderr("launchctl load failed", async () => io.execFile("launchctl", ["load", "-w", installPath]));
+            await runAndSurfaceStderr("launchctl start failed", async () => io.execFile("launchctl", ["start", SERVICE_ID]));
         },
-        // eslint-disable-next-line @typescript-eslint/require-await
         async stop() {
-            const installPath = this.getInstallPath();
-            execSync("launchctl unload \"" + installPath + "\"", { stdio: "pipe" });
+            await runAndSurfaceStderr("launchctl unload failed", async () => io.execFile("launchctl", ["unload", io.getServiceFilePath()]));
         },
         async uninstall() {
-            const installPath = this.getInstallPath();
+            const installPath = io.getServiceFilePath();
             // Unload the service first.
             try {
-                execSync("launchctl unload \"" + installPath + "\"", { stdio: "pipe" });
+                await io.execFile("launchctl", ["unload", installPath]);
             }
             catch {
-                // Ignore errors if service wasn't loaded.
+                // Ignore errors if the service was not loaded.
             }
             // Remove the plist file.
-            await fsPromises.rm(installPath, { force: true });
+            await io.rm(installPath, { force: true });
         }
     };
 }
 /* Generates a systemd user service unit file for Linux. The unit is installed to ~/.config/systemd/user/ and configured with:
- * - Restart=always: Restart automatically if the process exits
- * - RestartSec=5: Wait 5 seconds before restarting
- * - WantedBy=default.target: Start when user session begins
+ * - Restart=always: Restart automatically if the process exits.
+ * - RestartSec=5: Wait 5 seconds before restarting.
+ * - WantedBy=default.target: Start when user session begins.
+ *
+ * Linux deliberately does not redirect stdout/stderr to files - systemd captures them to the journal, which is the native Linux logging surface (journalctl
+ * --user -u prismcast).
  */
 /**
  * Creates a systemd service generator for Linux.
+ * @param io - The generator I/O context.
  * @returns A ServiceGenerator for systemd.
  */
-function createSystemdGenerator() {
+function createSystemdGenerator(io) {
+    /**
+     * Builds the systemd unit file from a service definition.
+     * @param definition - The service definition to serialize.
+     * @returns The unit file content as a UTF-8 string.
+     */
+    function generateUnit(definition) {
+        const envLines = sortedEnvEntries(definition.envVars).map(([key, value]) => "Environment=\"" + key + "=" + value + "\"").join("\n");
+        return [
+            "[Unit]",
+            "Description=" + SERVICE_NAME + " Streaming Server",
+            "After=network.target",
+            "",
+            "[Service]",
+            "Type=simple",
+            "ExecStart=" + definition.nodePath + " " + definition.entryPoint,
+            "WorkingDirectory=" + definition.workingDir,
+            "Restart=always",
+            "RestartSec=5",
+            envLines,
+            "",
+            "[Install]",
+            "WantedBy=default.target",
+            ""
+        ].join("\n");
+    }
     return {
-        generate(options) {
-            const nodePath = getNodeExecutablePath();
-            const entryPoint = getPrismCastEntryPoint();
-            const workingDir = getPrismCastWorkingDirectory();
-            // Build environment variables. Always include PRISMCAST_SERVICE=1 for service detection.
-            const envVars = { PRISMCAST_SERVICE: "1", ...options.envVars };
-            // Generate Environment= lines, sorted alphabetically.
-            const envLines = Object.entries(envVars).sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => "Environment=\"" + key + "=" + value + "\"").join("\n");
-            // Generate the unit file content.
-            return [
-                "[Unit]",
-                "Description=" + SERVICE_NAME + " Streaming Server",
-                "After=network.target",
-                "",
-                "[Service]",
-                "Type=simple",
-                "ExecStart=" + nodePath + " " + entryPoint,
-                "WorkingDirectory=" + workingDir,
-                "Restart=always",
-                "RestartSec=5",
-                envLines,
-                "",
-                "[Install]",
-                "WantedBy=default.target",
-                ""
-            ].join("\n");
-        },
-        getInstallPath() {
-            return getServiceFilePath();
-        },
-        async install(content) {
-            const installPath = this.getInstallPath();
-            const installDir = getServiceFileDirectory();
-            const logsDir = getLogsDirectory();
+        async install(definition) {
+            const installPath = io.getServiceFilePath();
+            const installDir = io.getServiceFileDirectory();
             // Ensure directories exist.
-            await fsPromises.mkdir(installDir, { recursive: true });
-            await fsPromises.mkdir(logsDir, { recursive: true });
+            await io.mkdir(installDir, { recursive: true });
+            await io.mkdir(definition.logsDir, { recursive: true });
             // Write the unit file.
-            await fsPromises.writeFile(installPath, content, "utf8");
+            await io.writeFile(installPath, generateUnit(definition));
             // Reload systemd to pick up the new unit file.
             try {
-                execSync("systemctl --user daemon-reload", { stdio: "pipe" });
+                await io.execFile("systemctl", ["--user", "daemon-reload"]);
             }
             catch {
                 // Ignore if systemctl isn't available (shouldn't happen on systemd systems).
             }
             // Enable and start the service.
-            execSync("systemctl --user enable prismcast.service", { stdio: "pipe" });
-            execSync("systemctl --user start prismcast.service", { stdio: "pipe" });
+            await runAndSurfaceStderr("systemctl enable failed", async () => io.execFile("systemctl", ["--user", "enable", "prismcast.service"]));
+            await runAndSurfaceStderr("systemctl start failed", async () => io.execFile("systemctl", ["--user", "start", "prismcast.service"]));
         },
-        // eslint-disable-next-line @typescript-eslint/require-await
         async isInstalled() {
-            return fs.existsSync(this.getInstallPath());
+            return fileExists(io, io.getServiceFilePath());
         },
-        // eslint-disable-next-line @typescript-eslint/require-await
         async isRunning() {
             try {
-                const result = execSync("systemctl --user is-active prismcast.service", { encoding: "utf8", stdio: "pipe" });
-                return result.trim() === "active";
+                const { stdout } = await io.execFile("systemctl", ["--user", "is-active", "prismcast.service"]);
+                return stdout.trim() === "active";
             }
             catch {
                 return false;
@@ -235,34 +269,32 @@ function createSystemdGenerator() {
         },
         platform: "linux",
         serviceManager: "systemd",
-        // eslint-disable-next-line @typescript-eslint/require-await
         async start() {
-            execSync("systemctl --user start prismcast.service", { stdio: "pipe" });
+            await runAndSurfaceStderr("systemctl start failed", async () => io.execFile("systemctl", ["--user", "start", "prismcast.service"]));
         },
-        // eslint-disable-next-line @typescript-eslint/require-await
         async stop() {
-            execSync("systemctl --user stop prismcast.service", { stdio: "pipe" });
+            await runAndSurfaceStderr("systemctl stop failed", async () => io.execFile("systemctl", ["--user", "stop", "prismcast.service"]));
         },
         async uninstall() {
-            const installPath = this.getInstallPath();
+            const installPath = io.getServiceFilePath();
             // Stop and disable the service.
             try {
-                execSync("systemctl --user stop prismcast.service", { stdio: "pipe" });
+                await io.execFile("systemctl", ["--user", "stop", "prismcast.service"]);
             }
             catch {
                 // Ignore if not running.
             }
             try {
-                execSync("systemctl --user disable prismcast.service", { stdio: "pipe" });
+                await io.execFile("systemctl", ["--user", "disable", "prismcast.service"]);
             }
             catch {
                 // Ignore if not enabled.
             }
             // Remove the unit file.
-            await fsPromises.rm(installPath, { force: true });
+            await io.rm(installPath, { force: true });
             // Reload systemd.
             try {
-                execSync("systemctl --user daemon-reload", { stdio: "pipe" });
+                await io.execFile("systemctl", ["--user", "daemon-reload"]);
             }
             catch {
                 // Ignore.
@@ -270,165 +302,253 @@ function createSystemdGenerator() {
         }
     };
 }
-/* Uses Windows Task Scheduler to run PrismCast at user logon. Three files in the data directory define the service: a batch startup script (.cmd) with environment
- * setup and the node invocation, a VBScript wrapper (.vbs) that launches it with a hidden console window, and a Task Scheduler XML definition (.xml) imported via
- * schtasks /Create /XML. The XML format avoids the shell quoting issues inherent in schtasks /TR and enables advanced task settings (restart on failure, unlimited
- * execution time, battery policy) that command-line flags cannot express. All schtasks calls use execFileSync to bypass cmd.exe shell interpretation entirely.
+/* Registers a Windows Task Scheduler task for PrismCast. The architecture is:
+ *
+ * - One support file: a PowerShell launcher (.ps1) that sets environment variables and spawns node with stdout/stderr redirected to the data directory. The
+ *   launcher serves the same role as the macOS plist's EnvironmentVariables dict and the systemd unit's Environment= lines - it is the persistent, human-readable
+ *   definition of the service's runtime.
+ *
+ * - One registration mechanism: the PowerShell ScheduledTasks module (Register-ScheduledTask, Start-ScheduledTask, etc.), which is the Task Scheduler 2.0 COM
+ *   surface exposed as typed cmdlets. We do not emit Task Scheduler XML and we do not invoke schtasks.exe. That choice eliminates the MSXML encoding dialect, the
+ *   shell-quoting hazards of schtasks /TR, and the need to get the Task XML schema's element order exactly right.
+ *
+ * - Task Scheduler spawns `powershell.exe -WindowStyle Hidden -File <launcher.ps1>`. PowerShell with -WindowStyle Hidden suppresses the console window natively on
+ *   Windows 10+, so no .vbs launcher is needed. VBScript was deprecated by Microsoft in 2024.
+ *
+ * All PowerShell invocations from Node go through invokePowerShell(), which documents the single argument-escape rule in its docstring. Values flow through Node's
+ * execFile without shell interpretation, and inside the PowerShell command string the one escape surface is single-quote doubling - see invokePowerShell below.
  */
 /**
- * Escapes a string for use in a Windows batch (.cmd) file. Literal percent characters must be doubled because batch interprets % as variable expansion even inside
- * quoted strings.
- * @param value - The string to escape.
- * @returns The escaped string safe for batch files.
+ * Escapes a value for embedding inside a single-quoted PowerShell string. PowerShell's single-quoted strings are literal (no interpolation, no backslash escapes);
+ * the only character that requires escaping is the single quote itself, which is written as two consecutive single quotes.
+ * @param value - The value to escape.
+ * @returns The value with internal single quotes doubled.
  */
-function escapeBatchValue(value) {
-    return value.replaceAll("%", "%%");
+function escapePowerShellSingleQuoted(value) {
+    return value.replaceAll("'", "''");
 }
+/**
+ * Wraps a value in a PowerShell single-quoted string literal, escaping any internal single quotes.
+ * @param value - The value to quote.
+ * @returns The PowerShell literal (including the surrounding quotes).
+ */
+function powerShellLiteral(value) {
+    return "'" + escapePowerShellSingleQuoted(value) + "'";
+}
+/**
+ * Builds a PowerShell invocation as a function bound to the supplied IO. The scriptBody is expected to declare its inputs via a param() clause at the top; each
+ * argument is serialized through powerShellLiteral() and appended to the command after the scriptblock, so PowerShell's own parser binds them to the declared
+ * parameters.
+ *
+ * The only escape surface in this path is the single-quote doubling performed by powerShellLiteral(). That one rule is total: inside a PowerShell single-quoted
+ * string, no other character has meaning - there is no interpolation, no backslash escape, no subshell, no variable expansion - and Windows filesystem rules forbid
+ * the double-quote character that could let a path escape the outer literal quoting we use inside the launcher's ArgumentList. Node's execFile then passes the
+ * composed command string to powershell.exe as a single UTF-16 argv element, bypassing cmd.exe entirely and eliminating shell-level quoting concerns.
+ *
+ * On failure, any stderr text that PowerShell wrote (e.g., a cmdlet's error record) is folded into the thrown Error's message by runAndSurfaceStderr, and the
+ * original Error is attached via the cause chain so programmatic consumers retain access to the structured failure details.
+ * @param io - The generator I/O context.
+ * @returns A function that runs a PowerShell script body with the given positional arguments.
+ */
+function makePowerShellInvoker(io) {
+    return async (scriptBody, args = []) => {
+        const quotedArgs = args.map((value) => powerShellLiteral(value)).join(" ");
+        const command = "& { " + scriptBody + " } " + quotedArgs;
+        await runAndSurfaceStderr("PowerShell invocation failed", async () => io.execFile("powershell.exe", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", command]));
+    };
+}
+/* Script bodies for Task Scheduler operations. Each script is a self-contained PowerShell block that reads its inputs from positional parameters - never from string
+ * interpolation or inline variables - so that Node-side argument quoting is always the single-quoted-literal escape and nothing else.
+ */
+/* Registers (or replaces) the PrismCast Task Scheduler task. Takes two positional parameters: the task name and the absolute path to the launcher .ps1 file.
+ *
+ * The first step stops any currently-running instance of the existing task and waits for its process to actually terminate before we replace the definition. Two
+ * Microsoft-documented facts make this wait necessary: Stop-ScheduledTask initiates the stop but returns before the process has exited (there is no -Wait
+ * switch and no built-in completion primitive), and "You can make changes to a task definition even if an instance of the task is running. The changes do not
+ * affect the current instance." (Set-ScheduledTask docs, which applies equally to Register-ScheduledTask -Force). Without the poll loop, `prismcast service
+ * install --force` on a running service would leave the old node process holding port 5589 while Start-ScheduledTask spawns a new node that fails to bind,
+ * triggering the 1-minute RestartOnFailure backoff and silently delaying the service becoming available for up to three minutes.
+ *
+ * The poll checks State every 250 ms against a 30-second ceiling. The ceiling is a belt-and-suspenders fallback - if the old process is pathologically stuck,
+ * Task Scheduler's own TerminateProcess path will clean it up later. A null state means the task was unregistered concurrently, which is also a valid "not
+ * running anymore" exit.
+ *
+ * The action invokes powershell.exe with -WindowStyle Hidden and -File pointing at the launcher. -ExecutionPolicy Bypass is the Microsoft-documented pattern for
+ * installer-scripted scenarios - it disables the interactive-use execution policy gate without globally weakening script security on the machine.
+ *
+ * The trigger fires at user logon. The principal runs the task as the current user with Interactive logon and Limited (LeastPrivilege) run level, mirroring the
+ * user-scoped semantics of launchd user agents and systemd --user units. On workgroup machines where USERDOMAIN is not set, we fall back to COMPUTERNAME.
+ *
+ * Settings express unlimited execution time (PT0S), battery-friendly behavior, ignore-new-instance policy, and automatic restart on failure (3 attempts, 1-minute
+ * interval).
+ */
+const WINDOWS_REGISTER_SCRIPT = [
+    "param($TaskName, $Launcher)",
+    "$existing = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue",
+    "if($existing) {",
+    "  Stop-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue | Out-Null",
+    "  $deadline = (Get-Date).AddSeconds(30)",
+    "  while((Get-Date) -lt $deadline) {",
+    "    $state = (Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue).State",
+    "    if(($null -eq $state) -or ($state -ne 'Running')) { break }",
+    "    Start-Sleep -Milliseconds 250",
+    "  }",
+    "}",
+    "$userId = $env:USERDOMAIN + '\\' + $env:USERNAME",
+    "if(-not $env:USERDOMAIN) { $userId = $env:COMPUTERNAME + '\\' + $env:USERNAME }",
+    "$taskArg = '-NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -File \"' + $Launcher + '\"'",
+    "$action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument $taskArg",
+    "$trigger = New-ScheduledTaskTrigger -AtLogOn -User $userId",
+    "$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -ExecutionTimeLimit (New-TimeSpan -Seconds 0) " +
+        "-MultipleInstances IgnoreNew -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1)",
+    "$principal = New-ScheduledTaskPrincipal -UserId $userId -LogonType Interactive -RunLevel Limited",
+    "Register-ScheduledTask -TaskName $TaskName -Action $action -Trigger $trigger -Settings $settings -Principal $principal -Force | Out-Null"
+].join("\n");
+/* Unregisters the task. Takes the task name as its sole parameter.
+ */
+const WINDOWS_UNREGISTER_SCRIPT = [
+    "param($TaskName)",
+    "Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false -ErrorAction SilentlyContinue | Out-Null"
+].join("\n");
+/* Starts the task, re-enabling it first in case a previous stop() call left it disabled. Takes the task name as its sole parameter.
+ */
+const WINDOWS_START_SCRIPT = [
+    "param($TaskName)",
+    "Enable-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue | Out-Null",
+    "Start-ScheduledTask -TaskName $TaskName | Out-Null"
+].join("\n");
+/* Stops the task. Disables it first to prevent the RestartOnFailure policy from re-launching the process after we stop it. Start-ScheduledTask in WINDOWS_START_SCRIPT
+ * re-enables the task. Takes the task name as its sole parameter.
+ */
+const WINDOWS_STOP_SCRIPT = [
+    "param($TaskName)",
+    "Disable-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue | Out-Null",
+    "Stop-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue | Out-Null"
+].join("\n");
+/* Exits 0 if the task is registered, 1 otherwise. Takes the task name as its sole parameter.
+ */
+const WINDOWS_IS_INSTALLED_SCRIPT = [
+    "param($TaskName)",
+    "if(Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue) { exit 0 } else { exit 1 }"
+].join("\n");
+/* Exits 0 if the task's State property is 'Running', 1 otherwise. Takes the task name as its sole parameter.
+ */
+const WINDOWS_IS_RUNNING_SCRIPT = [
+    "param($TaskName)",
+    "$task = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue",
+    "if($task -and ($task.State -eq 'Running')) { exit 0 } else { exit 1 }"
+].join("\n");
 /**
  * Creates a Windows Task Scheduler generator.
+ * @param io - The generator I/O context.
  * @returns A ServiceGenerator for Windows Task Scheduler.
  */
-function createWindowsSchedulerGenerator() {
+function createWindowsSchedulerGenerator(io) {
     const taskName = SERVICE_NAME;
+    const invokePowerShell = makePowerShellInvoker(io);
     /**
-     * Returns the path to the VBScript wrapper file that launches PrismCast with a hidden console window.
-     * @returns The absolute path to the .vbs file in the data directory.
-     */
-    function getVbsPath() {
-        return path.join(getServiceFileDirectory(), "prismcast-service.vbs");
-    }
-    /**
-     * Returns the path to the Task Scheduler XML definition file.
-     * @returns The absolute path to the .xml file in the data directory.
+     * Generates the PowerShell launcher script (.ps1) that Task Scheduler will invoke at user logon. The launcher sets environment variables and spawns node via
+     * Start-Process, with stdout and stderr redirected to separate log files in the data directory. Start-Process binds the child's stream file descriptors directly
+     * to the output files, so PowerShell's host-level encoding conversions never touch the stream - node's raw UTF-8 bytes land unchanged in the log file.
+     *
+     * Path and value embedding uses PowerShell single-quoted string literals, which are fully literal (no interpolation, no backslash escapes). The only escape
+     * needed is doubling any internal single-quote character. Windows filesystem rules forbid double quotes in paths, so wrapping the Start-Process ArgumentList in
+     * literal double quotes safely handles paths with spaces.
+     *
+     * The node and entry point paths are also written as comment metadata near the top of the file, so that stale-path detection can recover them without having to
+     * parse the Start-Process invocation.
+     * @param definition - The service definition to serialize.
+     * @returns The launcher content as a UTF-8 string with a leading BOM.
      */
-    function getXmlPath() {
-        return path.join(getServiceFileDirectory(), "prismcast-task.xml");
+    function generateLauncher(definition) {
+        const stdoutLog = path.join(definition.logsDir, "service-stdout.log");
+        const stderrLog = path.join(definition.logsDir, "service-stderr.log");
+        const envLines = sortedEnvEntries(definition.envVars).map(([key, value]) => "$env:" + key + " = " + powerShellLiteral(value));
+        // The Start-Process ArgumentList is a PowerShell single-quoted string that contains a literal double-quoted entry-point path. Windows disallows double quotes
+        // in paths, so this quoting is always well-formed.
+        const argumentList = "'\"" + escapePowerShellSingleQuoted(definition.entryPoint) + "\"'";
+        // PowerShell 5.1's default file encoding is ambiguous. A leading UTF-8 BOM (U+FEFF) ensures every supported PowerShell version parses the launcher as UTF-8.
+        // Windows line endings (CRLF) are conventional for .ps1 files and match what tools like Set-Content produce.
+        return "\uFEFF" + [
+            "# PrismCast service launcher.",
+            "#",
+            "# This file is auto-generated by `prismcast service install`. Manual edits will be overwritten the next time the service is installed or restarted.",
+            "#",
+            "# The following metadata lines are read back by `prismcast service status` to detect stale paths after a PrismCast upgrade. Do not remove them.",
+            "# node: " + definition.nodePath,
+            "# entry: " + definition.entryPoint,
+            "",
+            "# Environment variables for the service process.",
+            ...envLines,
+            "",
+            "# Spawn node with stdout and stderr redirected to separate log files. Start-Process binds the child's file descriptors directly, so byte-level content flows",
+            "# through unmodified. WindowStyle 'Hidden' gives node its own hidden console - the reliable pattern for combining stream redirection with a suppressed window",
+            "# across every supported PowerShell version. Since the outer PowerShell is already launched hidden by Task Scheduler, the user sees no window at any point.",
+            "# -Wait keeps the PowerShell host alive until node exits, so Task Scheduler's RestartOnFailure policy can observe non-zero exit codes and restart as intended.",
+            "$startArgs = @{",
+            "  ArgumentList = " + argumentList,
+            "  FilePath = " + powerShellLiteral(definition.nodePath),
+            "  PassThru = $true",
+            "  RedirectStandardError = " + powerShellLiteral(stderrLog),
+            "  RedirectStandardOutput = " + powerShellLiteral(stdoutLog),
+            "  Wait = $true",
+            "  WindowStyle = 'Hidden'",
+            "  WorkingDirectory = " + powerShellLiteral(definition.workingDir),
+            "}",
+            "",
+            "$process = Start-Process @startArgs",
+            "exit $process.ExitCode",
+            ""
+        ].join("\r\n");
     }
     /**
-     * Generates the Task Scheduler XML definition. The XML format provides structured task configuration without shell quoting and supports advanced settings
-     * (restart on failure, no execution time limit, battery policy) that schtasks command-line flags cannot express. Element ordering follows the Task Scheduler
-     * XML schema.
-     * @param vbsFilePath - The absolute path to the VBScript wrapper that launches PrismCast.
-     * @returns The XML content for the task definition.
+     * Removes the legacy three-file service artifacts (.cmd launcher, .vbs wrapper, .xml task definition) and the long-obsolete service-installed.marker file from
+     * prior PrismCast versions. Safe to call unconditionally; missing files are silently ignored.
+     * @param installDir - The service file directory.
      */
-    function generateTaskXml(vbsFilePath) {
-        return [
-            "<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
-            "<Task version=\"1.2\" xmlns=\"http://schemas.microsoft.com/windows/2004/02/mit/task\">",
-            "  <RegistrationInfo>",
-            "    <Description>" + escapeXml(SERVICE_NAME + " Streaming Server") + "</Description>",
-            "  </RegistrationInfo>",
-            "  <Triggers>",
-            "    <LogonTrigger>",
-            "      <Enabled>true</Enabled>",
-            "    </LogonTrigger>",
-            "  </Triggers>",
-            "  <Principals>",
-            "    <Principal id=\"Author\">",
-            "      <LogonType>InteractiveToken</LogonType>",
-            "      <RunLevel>HighestAvailable</RunLevel>",
-            "    </Principal>",
-            "  </Principals>",
-            "  <Settings>",
-            "    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>",
-            "    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>",
-            "    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>",
-            "    <Enabled>true</Enabled>",
-            "    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>",
-            "    <RestartOnFailure>",
-            "      <Interval>PT5S</Interval>",
-            "      <Count>3</Count>",
-            "    </RestartOnFailure>",
-            "  </Settings>",
-            "  <Actions Context=\"Author\">",
-            "    <Exec>",
-            "      <Command>wscript.exe</Command>",
-            "      <Arguments>" + escapeXml("\"" + vbsFilePath + "\"") + "</Arguments>",
-            "    </Exec>",
-            "  </Actions>",
-            "</Task>",
-            ""
-        ].join("\n");
+    async function removeLegacyWindowsArtifacts(installDir) {
+        const legacyFiles = [
+            path.join(installDir, "prismcast-service.cmd"),
+            path.join(installDir, "prismcast-service.vbs"),
+            path.join(installDir, "prismcast-task.xml"),
+            path.join(installDir, "service-installed.marker")
+        ];
+        await Promise.all(legacyFiles.map(async (filePath) => io.rm(filePath, { force: true })));
     }
     return {
-        generate(options) {
-            const nodePath = getNodeExecutablePath();
-            const entryPoint = getPrismCastEntryPoint();
-            const workingDir = getPrismCastWorkingDirectory();
-            // Build environment variables. Always include PRISMCAST_SERVICE=1 for service detection.
-            const envVars = { PRISMCAST_SERVICE: "1", ...options.envVars };
-            // Generate set commands for environment variables, sorted alphabetically. Values are escaped for batch interpretation where literal % must be doubled.
-            const envLines = Object.entries(envVars)
-                .sort(([a], [b]) => a.localeCompare(b))
-                .map(([key, value]) => "set \"" + key + "=" + escapeBatchValue(value) + "\"");
-            // Generate the batch file content. Each line uses exactly one level of quoting because the batch file is a standalone script, not an inline argument embedded
-            // in another command. The rem lines provide machine-readable path metadata for stale path detection, parsed by getServicePaths(). CRLF line endings follow
-            // Windows batch file convention.
-            return [
-                "@echo off",
-                "rem node:" + nodePath,
-                "rem entry:" + entryPoint,
-                "cd /d \"" + escapeBatchValue(workingDir) + "\"",
-                ...envLines,
-                "\"" + escapeBatchValue(nodePath) + "\" \"" + escapeBatchValue(entryPoint) + "\""
-            ].join("\r\n") + "\r\n";
-        },
-        getInstallPath() {
-            return getServiceFilePath();
-        },
-        async install(content) {
-            const cmdPath = getServiceFilePath();
-            const vbsPath = getVbsPath();
-            const xmlPath = getXmlPath();
-            const installDir = getServiceFileDirectory();
-            const logsDir = getLogsDirectory();
+        async install(definition) {
+            const launcherPath = io.getServiceFilePath();
+            const installDir = io.getServiceFileDirectory();
             // Ensure directories exist.
-            await fsPromises.mkdir(installDir, { recursive: true });
-            await fsPromises.mkdir(logsDir, { recursive: true });
-            // Delete existing task if it exists.
-            try {
-                execFileSync("schtasks", ["/Delete", "/TN", taskName, "/F"], { stdio: "pipe" });
-            }
-            catch {
-                // Ignore if task doesn't exist.
-            }
-            // Write the batch startup script.
-            await fsPromises.writeFile(cmdPath, content, "utf8");
-            // Write the VBScript wrapper that launches the batch file with a hidden console window. The WshShell.Run second parameter (0) specifies the vbHide window
-            // style, and the third parameter (False) means don't wait for the script to finish.
-            const vbsContent = "Set WshShell = CreateObject(\"WScript.Shell\")\r\nWshShell.Run \"\"\"" + cmdPath + "\"\"\", 0, False\r\n";
-            await fsPromises.writeFile(vbsPath, vbsContent, "utf8");
-            // Write the Task Scheduler XML definition and import it. Using XML import instead of schtasks /TR avoids all shell quoting issues and enables advanced task
-            // settings that command-line flags cannot express.
-            const xmlContent = generateTaskXml(vbsPath);
-            await fsPromises.writeFile(xmlPath, xmlContent, "utf8");
-            // Import the task definition. execFileSync passes arguments directly to the Windows API, bypassing cmd.exe shell interpretation entirely.
-            execFileSync("schtasks", ["/Create", "/XML", xmlPath, "/TN", taskName, "/F"], { stdio: "pipe" });
-            // Clean up legacy marker file from previous versions that used a separate metadata file for path tracking.
-            await fsPromises.rm(path.join(installDir, "service-installed.marker"), { force: true });
-            // Start the task immediately.
+            await io.mkdir(installDir, { recursive: true });
+            await io.mkdir(definition.logsDir, { recursive: true });
+            // Remove legacy artifacts from pre-PowerShell versions so the data directory contains only the current launcher.
+            await removeLegacyWindowsArtifacts(installDir);
+            // Write the launcher .ps1 with a UTF-8 BOM for unambiguous PowerShell parsing across versions.
+            await io.writeFile(launcherPath, generateLauncher(definition));
+            // Register (or replace) the scheduled task. -Force in the registration script handles reinstall.
+            await invokePowerShell(WINDOWS_REGISTER_SCRIPT, [taskName, launcherPath]);
+            // Start the task immediately so the user does not need to log out and back in.
             try {
-                execFileSync("schtasks", ["/Run", "/TN", taskName], { stdio: "pipe" });
+                await invokePowerShell(WINDOWS_START_SCRIPT, [taskName]);
             }
             catch {
-                // Ignore if start fails.
+                // Best-effort start. The task is registered and will fire at next logon regardless.
             }
         },
-        // eslint-disable-next-line @typescript-eslint/require-await
         async isInstalled() {
             try {
-                execFileSync("schtasks", ["/Query", "/TN", taskName], { stdio: "pipe" });
+                await invokePowerShell(WINDOWS_IS_INSTALLED_SCRIPT, [taskName]);
                 return true;
             }
             catch {
                 return false;
             }
         },
-        // eslint-disable-next-line @typescript-eslint/require-await
         async isRunning() {
             try {
-                const result = execFileSync("schtasks", ["/Query", "/TN", taskName, "/FO", "CSV", "/NH"], { encoding: "utf8", stdio: "pipe" });
-                return result.includes("Running");
+                await invokePowerShell(WINDOWS_IS_RUNNING_SCRIPT, [taskName]);
+                return true;
             }
             catch {
                 return false;
@@ -436,106 +556,85 @@ function createWindowsSchedulerGenerator() {
         },
         platform: "windows",
         serviceManager: "windows-scheduler",
-        // eslint-disable-next-line @typescript-eslint/require-await
         async start() {
-            // Re-enable the task (it may have been disabled by stop() to prevent RestartOnFailure from restarting the process) and run it.
-            try {
-                execFileSync("schtasks", ["/Change", "/TN", taskName, "/Enable"], { stdio: "pipe" });
-            }
-            catch {
-                // Ignore if already enabled or task doesn't exist.
-            }
-            execFileSync("schtasks", ["/Run", "/TN", taskName], { stdio: "pipe" });
+            await invokePowerShell(WINDOWS_START_SCRIPT, [taskName]);
         },
-        // eslint-disable-next-line @typescript-eslint/require-await
         async stop() {
-            // Disable the task first to prevent RestartOnFailure from automatically restarting the process after we terminate it.
-            try {
-                execFileSync("schtasks", ["/Change", "/TN", taskName, "/Disable"], { stdio: "pipe" });
-            }
-            catch {
-                // Ignore if task doesn't exist.
-            }
-            execFileSync("schtasks", ["/End", "/TN", taskName], { stdio: "pipe" });
+            await invokePowerShell(WINDOWS_STOP_SCRIPT, [taskName]);
         },
         async uninstall() {
-            const cmdPath = getServiceFilePath();
-            const vbsPath = getVbsPath();
-            const xmlPath = getXmlPath();
-            // Delete the scheduled task.
+            const launcherPath = io.getServiceFilePath();
+            const installDir = io.getServiceFileDirectory();
+            // Deregister the task. SilentlyContinue in the script makes this a no-op if the task was never registered.
             try {
-                execFileSync("schtasks", ["/Delete", "/TN", taskName, "/F"], { stdio: "pipe" });
+                await invokePowerShell(WINDOWS_UNREGISTER_SCRIPT, [taskName]);
             }
             catch {
-                // Ignore if task doesn't exist.
+                // Ignore - task may not exist.
             }
-            // Remove all service files and legacy marker file from previous versions.
-            await Promise.all([cmdPath, vbsPath, xmlPath, path.join(getServiceFileDirectory(), "service-installed.marker")].map(async (filePath) => fsPromises.rm(filePath, { force: true })));
+            // Remove the launcher and any residual legacy artifacts.
+            await io.rm(launcherPath, { force: true });
+            await removeLegacyWindowsArtifacts(installDir);
         }
     };
 }
 /**
  * Reads the existing service file and extracts the node binary and PrismCast entry point paths. Each platform has its own format: launchd plist XML, systemd unit
- * ExecStart line, or Windows batch startup script with rem-prefixed path comments.
- * @returns The extracted paths, or null if the file doesn't exist or can't be parsed.
+ * ExecStart line, or Windows PowerShell launcher with comment metadata.
+ * @param io - The generator I/O context. Defaults to createDefaultGeneratorIO() which wires real runtime I/O.
+ * @returns The extracted paths, or null if the file does not exist or cannot be parsed.
  */
-export function getServicePaths() {
-    const filePath = getServiceFilePath();
-    if (!fs.existsSync(filePath)) {
+export function getServicePaths(io = createDefaultGeneratorIO()) {
+    const filePath = io.getServiceFilePath();
+    if (!io.existsSync(filePath)) {
         return null;
     }
     let content;
     try {
-        content = fs.readFileSync(filePath, "utf8");
+        content = io.readFileSync(filePath);
     }
     catch {
         return null;
     }
-    switch (getPlatform()) {
-        // Launchd plist: ProgramArguments contains two <string> elements — first is the node path, second is the entry point.
+    switch (io.getPlatform()) {
+        // Launchd plist: the ProgramArguments array contains two <string> elements - the first is the node path, the second is the entry point. We slice to the section
+        // after the ProgramArguments key, then take the first two string values via matchAll + iterator helpers (lazy, early-terminating, no intermediate arrays).
         case "darwin": {
-            const stringPattern = /<string>([^<]+)<\/string>/g;
-            const matches = [];
-            let match;
-            // Walk the ProgramArguments array. We look for the section after the ProgramArguments key and extract the first two string values.
             const programArgsIndex = content.indexOf("<key>ProgramArguments</key>");
             if (programArgsIndex === -1) {
                 return null;
             }
-            // Extract strings from the <array> section following ProgramArguments.
-            const arraySection = content.slice(programArgsIndex);
-            while ((match = stringPattern.exec(arraySection)) !== null) {
-                matches.push(match[1]);
-                if (matches.length === 2) {
-                    break;
-                }
-            }
-            if (matches.length < 2) {
+            const [nodePath, entryPoint] = content.slice(programArgsIndex)
+                .matchAll(/<string>([^<]+)<\/string>/g)
+                .take(2)
+                .map((match) => match[1])
+                .toArray();
+            if (!nodePath || !entryPoint) {
                 return null;
             }
-            return { entryPoint: matches[1], nodePath: matches[0] };
+            return { entryPoint, nodePath };
         }
         // Systemd unit: ExecStart=<node> <entrypoint> on one line.
         case "linux": {
-            const execStartMatch = /^ExecStart=(.+)$/m.exec(content);
-            if (!execStartMatch) {
+            const execStart = /^ExecStart=(.+)$/m.exec(content)?.[1];
+            if (!execStart) {
                 return null;
             }
-            const parts = execStartMatch[1].split(" ");
-            if (parts.length < 2) {
+            const [nodePath, entryPoint] = execStart.split(" ");
+            if (!nodePath || !entryPoint) {
                 return null;
             }
-            return { entryPoint: parts[1], nodePath: parts[0] };
+            return { entryPoint, nodePath };
         }
-        // Windows: paths are stored as "rem node:<path>" and "rem entry:<path>" comments in the batch startup script (.cmd file). The .trim() handles CRLF line
-        // endings in batch files where \r would otherwise be captured by the regex.
+        // Windows: paths are stored as "# node:<path>" and "# entry:<path>" metadata comments near the top of the PowerShell launcher. The .trim() handles CRLF line
+        // endings where \r would otherwise be captured by the regex.
         case "windows": {
-            const nodeMatch = /^rem node:(.+)$/m.exec(content);
-            const entryMatch = /^rem entry:(.+)$/m.exec(content);
-            if (!nodeMatch || !entryMatch) {
+            const nodePath = /^# node:(.+)$/m.exec(content)?.[1]?.trim();
+            const entryPoint = /^# entry:(.+)$/m.exec(content)?.[1]?.trim();
+            if (!nodePath || !entryPoint) {
                 return null;
             }
-            return { entryPoint: entryMatch[1].trim(), nodePath: nodeMatch[1].trim() };
+            return { entryPoint, nodePath };
         }
         default: {
             return null;
@@ -545,71 +644,73 @@ export function getServicePaths() {
 /**
  * Checks whether the paths in the existing service file still exist on disk. This detects the common post-upgrade scenario where Homebrew or npm has moved the
  * installation to a new versioned directory and the old paths no longer resolve.
- * @returns A StalePathResult indicating which paths are missing, or null if the service file doesn't exist or can't be parsed.
+ * @param io - The generator I/O context. Defaults to createDefaultGeneratorIO() which wires real runtime I/O.
+ * @returns A StalePathResult indicating which paths are missing, or null if the service file does not exist or cannot be parsed.
  */
-export function detectStalePaths() {
-    const paths = getServicePaths();
+export function detectStalePaths(io = createDefaultGeneratorIO()) {
+    const paths = getServicePaths(io);
     if (!paths) {
         return null;
     }
-    const nodeStale = !fs.existsSync(paths.nodePath);
-    const entryStale = !fs.existsSync(paths.entryPoint);
+    const nodeStale = !io.existsSync(paths.nodePath);
+    const entryStale = !io.existsSync(paths.entryPoint);
     return {
         entryPoint: entryStale ? paths.entryPoint : undefined,
         nodePath: nodeStale ? paths.nodePath : undefined,
         stale: nodeStale || entryStale
     };
 }
-/* Returns the appropriate service generator for the current platform.
- */
 /**
  * Returns the service generator for the current platform.
+ * @param io - The generator I/O context. Defaults to createDefaultGeneratorIO() which wires real runtime I/O.
  * @returns The appropriate ServiceGenerator, or null if the platform is not supported.
  */
-export function getServiceGenerator() {
-    switch (getPlatform()) {
+export function getServiceGenerator(io = createDefaultGeneratorIO()) {
+    switch (io.getPlatform()) {
         case "darwin": {
-            return createLaunchdGenerator();
+            return createLaunchdGenerator(io);
         }
         case "linux": {
-            return createSystemdGenerator();
+            return createSystemdGenerator(io);
         }
         case "windows": {
-            return createWindowsSchedulerGenerator();
+            return createWindowsSchedulerGenerator(io);
         }
         default: {
             return null;
         }
     }
 }
+/* Env vars that belong in the service environment but are not declared in CONFIG_METADATA. PRISMCAST_DATA_DIR resolves before config.json is read
+ * (chicken-and-egg bootstrap), and PRISMCAST_DEBUG is a runtime-only setting parsed in the entry point - see src/index.ts where both are called out as special
+ * cases for the same reason.
+ */
+const BOOTSTRAP_ENV_VARS = ["PRISMCAST_DATA_DIR", "PRISMCAST_DEBUG"];
+/**
+ * Returns the full set of env var names that represent user-configurable PrismCast settings. Derived from CONFIG_METADATA (the documented single source of truth
+ * for configurable settings) plus the bootstrap-only variables enumerated above. Deriving from CONFIG_METADATA means new settings are automatically captured by
+ * the service layer the moment they are declared in config metadata - no second list to maintain.
+ * @returns An array of env var names.
+ */
+function getConfigurableEnvVarNames() {
+    const fromMetadata = Object.values(CONFIG_METADATA).flat().map((setting) => setting.envVar).filter((envVar) => envVar !== null);
+    return [...fromMetadata, ...BOOTSTRAP_ENV_VARS];
+}
 /**
- * Collects environment variables that should be persisted in the service file. This includes settings that differ from defaults or have been explicitly configured.
+ * Collects environment variables that should be persisted in the service definition. Captures every CONFIG_METADATA-declared env var (plus the bootstrap
+ * variables that cannot live there) that is currently set in process.env, so anything the user configured via env for this run is preserved into the installed
+ * service.
  * @returns A record of environment variable names to values.
  */
 export function collectServiceEnvironment() {
     const envVars = {};
     // Always capture PATH so that FFmpeg and other tools can be found. Service managers like launchd use a minimal PATH by default (/usr/bin:/bin:/usr/sbin:/sbin)
-    // which doesn't include Homebrew or other common tool locations.
-    if (process.env.PATH) {
-        envVars.PATH = process.env.PATH;
+    // which does not include Homebrew or other common tool locations.
+    const pathEnv = process.env["PATH"];
+    if (pathEnv) {
+        envVars["PATH"] = pathEnv;
     }
-    // Include key settings if they're set via environment. These are the settings most likely to be intentionally configured.
-    const keysToCapture = [
-        "AUDIO_BITRATE",
-        "CAPTURE_MODE",
-        "CHROME_BIN",
-        "FRAME_RATE",
-        "HOST",
-        "LOG_MAX_SIZE",
-        "PORT",
-        "PRISMCAST_CHROME_DATA_DIR",
-        "PRISMCAST_DATA_DIR",
-        "PRISMCAST_DEBUG",
-        "PRISMCAST_LOG_FILE",
-        "QUALITY_PRESET",
-        "VIDEO_BITRATE"
-    ];
-    for (const key of keysToCapture) {
+    for (const key of getConfigurableEnvVarNames()) {
         const value = process.env[key];
         if (value !== undefined) {
             envVars[key] = value;
@@ -617,4 +718,19 @@ export function collectServiceEnvironment() {
     }
     return envVars;
 }
+/**
+ * Builds a ServiceDefinition from the current runtime context. Composes the platform helpers (node path, entry point, working directory, logs directory) with the
+ * collected service environment, and stamps PRISMCAST_SERVICE=1 for service-mode detection.
+ * @returns The structured service definition.
+ */
+export function buildServiceDefinition() {
+    const envVars = { PRISMCAST_SERVICE: "1", ...collectServiceEnvironment() };
+    return {
+        entryPoint: getPrismCastEntryPoint(),
+        envVars,
+        logsDir: getLogsDirectory(),
+        nodePath: getNodeExecutablePath(),
+        workingDir: getPrismCastWorkingDirectory()
+    };
+}
 //# sourceMappingURL=generators.js.map