@jmfederico/pi-web 1.202605.11 → 1.202605.13

package/dist/cli.js

@@ -1,14 +1,85 @@
 #!/usr/bin/env node
-import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { homedir, userInfo } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
-import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { defaultPiWebConfigPath, examplePiWebConfig } from "./config.js";
-const serviceDir = join(homedir(), ".config", "systemd", "user");
+import { defaultPiWebConfigPath, defaultPiWebDataDir, examplePiWebConfig } from "./config.js";
+import { checkNodePtyDarwinSpawnHelper, formatNodePtyDarwinSpawnHelperCheck } from "./server/diagnostics/nodePtySpawnHelper.js";
+const PI_WEB_PACKAGE_NAME = "@jmfederico/pi-web";
+const systemdServiceDir = join(homedir(), ".config", "systemd", "user");
+const launchdServiceDir = join(homedir(), "Library", "LaunchAgents");
+const logDir = join(defaultPiWebDataDir(), "logs");
 const sessiondServiceName = "pi-web-sessiond.service";
 const webServiceName = "pi-web.service";
+const uiDevServiceName = "pi-web-ui-dev.service";
+const serviceRefs = {
+    sessiond: {
+        id: "sessiond",
+        systemdName: sessiondServiceName,
+        launchdLabel: "com.pi-web.sessiond",
+        launchdPlistName: "com.pi-web.sessiond.plist",
+        logName: "sessiond.log",
+    },
+    web: {
+        id: "web",
+        systemdName: webServiceName,
+        launchdLabel: "com.pi-web.web",
+        launchdPlistName: "com.pi-web.web.plist",
+        logName: "web.log",
+    },
+    uiDev: {
+        id: "uiDev",
+        systemdName: uiDevServiceName,
+        launchdLabel: "com.pi-web.ui-dev",
+        launchdPlistName: "com.pi-web.ui-dev.plist",
+        logName: "ui-dev.log",
+    },
+};
+const productionServiceIds = ["sessiond", "web"];
+const startServiceOrder = ["sessiond", "web", "uiDev"];
+const stopServiceOrder = ["web", "uiDev", "sessiond"];
+function platformLabel() {
+    if (process.platform === "darwin")
+        return "macOS";
+    if (process.platform === "linux")
+        return "Linux";
+    if (process.platform === "win32")
+        return "Windows";
+    return process.platform;
+}
+function currentServiceBackend() {
+    if (process.platform === "linux")
+        return { kind: "systemd", label: "systemd user services" };
+    if (process.platform === "darwin")
+        return { kind: "launchd", label: "LaunchAgents" };
+    return undefined;
+}
+function requireServiceBackend(command) {
+    const backend = currentServiceBackend();
+    if (backend !== undefined)
+        return backend;
+    throw new Error(`\`${command}\` requires a supported per-user service manager (systemd user services or LaunchAgents) and is not supported on ${platformLabel()}.\n\n${manualRunAdvice()}`);
+}
+function supportsSystemdUserServices() {
+    return currentServiceBackend()?.kind === "systemd";
+}
+function manualRunAdvice() {
+    return [
+        "Run PI WEB manually from a checkout:",
+        "  npm run start:sessiond",
+        "  PI_WEB_PORT=8504 npm start",
+        "",
+        "For development in one terminal:",
+        "  npm run dev",
+        "",
+        "For split development, keep sessiond separate and run web/API plus Vite UI separately:",
+        "  npm run dev:sessiond",
+        "  npm run dev:web",
+        "  npm run dev:client",
+    ].join("\n");
+}
 function run(command, args, options = {}) {
     const result = spawnSync(command, args, { stdio: "inherit" });
     const status = result.status ?? 1;
@@ -16,9 +87,17 @@ function run(command, args, options = {}) {
         process.exit(status);
     return status;
 }
+function outputText(value) {
+    return typeof value === "string" ? value : "";
+}
 function capture(command, args) {
     const result = spawnSync(command, args, { encoding: "utf8" });
-    return { status: result.status ?? 1, stdout: result.stdout, stderr: result.stderr };
+    const errorMessage = result.error instanceof Error ? result.error.message : "";
+    const stderr = outputText(result.stderr);
+    return { status: result.status ?? 1, stdout: outputText(result.stdout), stderr: stderr === "" ? errorMessage : stderr };
+}
+function runQuiet(command, args) {
+    return capture(command, args).status;
 }
 function hasCommand(command) {
     return capture("/usr/bin/env", ["sh", "-c", `command -v ${command}`]).status === 0;
@@ -37,7 +116,7 @@ function isLingerEnabled() {
     return undefined;
 }
 function parseInstallOptions(args) {
-    const options = { host: "127.0.0.1", port: "8504" };
+    const options = { host: "127.0.0.1", port: "8504", mode: "production" };
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === undefined)
@@ -72,8 +151,11 @@ function parseInstallOptions(args) {
         else if (arg.startsWith("--config=")) {
             options.config = arg.slice("--config=".length);
         }
+        else if (arg === "--dev") {
+            options.mode = "dev";
+        }
         else if (arg === "--user-systemd") {
-            // Accepted for readability; user systemd is the only installer target for now.
+            // Accepted for backwards-compatible readability; PI WEB chooses the native user service backend automatically.
         }
         else {
             throw new Error(`Unknown install option: ${arg}`);
@@ -90,6 +172,17 @@ function fishSingleQuote(value) {
 function systemdEscape(value) {
     return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
 }
+function systemdQuotedValue(value) {
+    return `"${systemdEscape(value)}"`;
+}
+function xmlEscape(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&apos;");
+}
 function packageRootPath() {
     return dirname(dirname(fileURLToPath(import.meta.url)));
 }
@@ -100,14 +193,15 @@ function detectServiceShell() {
     const userShell = userInfo().shell ?? undefined;
     const envShell = process.env["SHELL"]?.trim();
     const detected = envShell === undefined || envShell === "" ? userShell : envShell;
-    const name = basename(detected ?? "").replace(/^-/u, "");
+    const name = basename(detected ?? "").replace(/^-/, "");
     if (name === "bash" || name === "zsh" || name === "fish") {
         return { name, executable: detected ?? name, detected: detected ?? name, fallback: false };
     }
     return { name: "bash", executable: "bash", ...(detected === undefined ? {} : { detected }), fallback: true };
 }
-function serviceShellCommand(command) {
-    return ["/usr/bin/env", detectServiceShell().executable, "-lc", command];
+function serviceShellCommand(command, cwd) {
+    const fullCommand = cwd === undefined ? command : `cd ${serviceShellQuote(cwd)} && ${command}`;
+    return ["/usr/bin/env", detectServiceShell().executable, "-lc", fullCommand];
 }
 function serviceShellExecPrefix() {
     return `/usr/bin/env ${detectServiceShell().executable} -lc`;
@@ -122,50 +216,48 @@ function checkSucceeds(command) {
     const [bin, ...args] = command;
     return bin !== undefined && capture(bin, args).status === 0;
 }
-function serviceShellCanFindCommand(command) {
+function serviceShellCanFindCommand(command, backend) {
     if (!checkSucceeds(serviceShellCommand(commandCheck(command))))
         return false;
-    return checkSucceeds(systemdUserServiceShellCommand(commandCheck(command)));
+    if (backend.kind === "systemd")
+        return checkSucceeds(systemdUserServiceShellCommand(commandCheck(command)));
+    return true;
 }
 function readableFileCheck(path) {
     const quoted = serviceShellQuote(path);
     return `test -r ${quoted} && printf '%s\\n' ${quoted}`;
 }
-function commandExecutable(command) {
+function commandExecutable(command, backend) {
     const shell = serviceShellLabel();
-    return {
-        command,
-        checks: [
-            [`${shell} can find ${command}`, serviceShellCommand(commandCheck(command))],
-            [`systemd user ${shell} can find ${command}`, systemdUserServiceShellCommand(commandCheck(command))],
-        ],
-    };
+    const checks = [[`${shell} can find ${command}`, serviceShellCommand(commandCheck(command))]];
+    if (backend.kind === "systemd") {
+        checks.push([`systemd user ${shell} can find ${command}`, systemdUserServiceShellCommand(commandCheck(command))]);
+    }
+    return { command, checks };
 }
-function bundledExecutable(command, entrypointPath) {
+function bundledExecutable(command, entrypointPath, backend) {
     const shell = serviceShellLabel();
     const check = readableFileCheck(entrypointPath);
-    return {
-        command: `node ${serviceShellQuote(entrypointPath)}`,
-        checks: [
-            [`${shell} can access bundled ${command} entrypoint`, serviceShellCommand(check)],
-            [`systemd user ${shell} can access bundled ${command} entrypoint`, systemdUserServiceShellCommand(check)],
-        ],
-    };
+    const checks = [[`${shell} can access bundled ${command} entrypoint`, serviceShellCommand(check)]];
+    if (backend.kind === "systemd") {
+        checks.push([`systemd user ${shell} can access bundled ${command} entrypoint`, systemdUserServiceShellCommand(check)]);
+    }
+    return { command: `node ${serviceShellQuote(entrypointPath)}`, checks };
 }
-function serviceExecutable(envName, command, entrypointPath) {
+function serviceExecutable(envName, command, entrypointPath, backend) {
     const configured = process.env[envName]?.trim();
     if (configured !== undefined && configured !== "")
         return { command: configured, checks: [] };
-    if (serviceShellCanFindCommand(command))
-        return commandExecutable(command);
+    if (serviceShellCanFindCommand(command, backend))
+        return commandExecutable(command, backend);
     if (existsSync(entrypointPath))
-        return bundledExecutable(command, entrypointPath);
-    return commandExecutable(command);
+        return bundledExecutable(command, entrypointPath, backend);
+    return commandExecutable(command, backend);
 }
-function resolveServiceExecutables() {
+function resolveServiceExecutables(backend) {
     return {
-        sessiond: serviceExecutable("PI_WEB_SESSIOND_EXEC", "pi-web-sessiond", packageEntrypointPath("sessiond")),
-        web: serviceExecutable("PI_WEB_SERVER_EXEC", "pi-web-server", packageEntrypointPath("server")),
+        sessiond: serviceExecutable("PI_WEB_SESSIOND_EXEC", "pi-web-sessiond", packageEntrypointPath("sessiond"), backend),
+        web: serviceExecutable("PI_WEB_SERVER_EXEC", "pi-web-server", packageEntrypointPath("server"), backend),
     };
 }
 function describeServiceShell() {
@@ -173,39 +265,148 @@ function describeServiceShell() {
     if (shell.fallback) {
         return shell.detected === undefined
             ? "could not detect a supported login shell; using bash"
-            : `detected ${shell.detected}; using bash because Pi Web currently supports bash, zsh, and fish`;
+            : `detected ${shell.detected}; using bash because PI WEB currently supports bash, zsh, and fish`;
     }
     return shell.detected === undefined ? shell.name : `${shell.name} (${shell.detected})`;
 }
-function sessiondUnit(executables) {
+function configEnvironment(options, configPath) {
+    return options.config === undefined ? {} : { PI_WEB_CONFIG: configPath };
+}
+function serviceRefList(ids) {
+    return ids.map((id) => serviceRefs[id]);
+}
+function allServiceRefs() {
+    return serviceRefList(["sessiond", "web", "uiDev"]);
+}
+function productionServiceRefs() {
+    return serviceRefList(productionServiceIds);
+}
+function orderServiceRefs(refs, order) {
+    const byId = new Map(refs.map((ref) => [ref.id, ref]));
+    return order.flatMap((id) => {
+        const ref = byId.get(id);
+        return ref === undefined ? [] : [ref];
+    });
+}
+function startOrder(refs) {
+    return orderServiceRefs(refs, startServiceOrder);
+}
+function stopOrder(refs) {
+    return orderServiceRefs(refs, stopServiceOrder);
+}
+function productionServiceDefinitions(options, configPath, executables) {
+    return [
+        {
+            ...serviceRefs.sessiond,
+            description: "PI WEB session daemon",
+            shellCommand: `exec ${executables.sessiond.command}`,
+            restart: "on-failure",
+            environment: {},
+        },
+        {
+            ...serviceRefs.web,
+            description: "PI WEB server",
+            shellCommand: `exec ${executables.web.command}`,
+            restart: "on-failure",
+            environment: configEnvironment(options, configPath),
+            after: ["sessiond"],
+            wants: ["sessiond"],
+        },
+    ];
+}
+function devRootPath() {
+    return resolve(process.cwd());
+}
+function validateDevCheckout(root) {
+    const packageJsonPath = join(root, "package.json");
+    if (!existsSync(packageJsonPath)) {
+        throw new Error(`Development mode must be installed from a PI WEB checkout. Missing package.json: ${packageJsonPath}`);
+    }
+    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    if (!isRecord(parsed) || parsed["name"] !== PI_WEB_PACKAGE_NAME) {
+        throw new Error(`Development mode must be installed from a PI WEB checkout. ${packageJsonPath} is not ${PI_WEB_PACKAGE_NAME}.`);
+    }
+    const scripts = parsed["scripts"];
+    if (!isRecord(scripts))
+        throw new Error(`Development mode requires npm scripts in ${packageJsonPath}.`);
+    const requiredScripts = ["start:sessiond", "dev:web", "dev:client"];
+    const missing = requiredScripts.filter((script) => typeof scripts[script] !== "string");
+    if (missing.length > 0)
+        throw new Error(`Development mode requires missing npm scripts: ${missing.join(", ")}.`);
+}
+function devServiceDefinitions(options, configPath, root) {
+    return [
+        {
+            ...serviceRefs.sessiond,
+            description: "PI WEB session daemon (dev)",
+            shellCommand: "exec npm run start:sessiond",
+            restart: "never",
+            environment: {},
+            workingDirectory: root,
+        },
+        {
+            ...serviceRefs.uiDev,
+            description: "PI WEB UI dev server",
+            shellCommand: `exec /usr/bin/env bash -c ${serviceShellQuote('trap "kill 0" EXIT; npm run dev:web & npm run dev:client & wait')}`,
+            restart: "never",
+            environment: configEnvironment(options, configPath),
+            after: ["sessiond"],
+            wants: ["sessiond"],
+            workingDirectory: root,
+        },
+    ];
+}
+function dependencyLine(name, ids) {
+    if (ids === undefined || ids.length === 0)
+        return "";
+    return `${name}=${ids.map((id) => serviceRefs[id].systemdName).join(" ")}\n`;
+}
+function environmentLines(environment) {
+    return Object.entries(environment)
+        .map(([key, value]) => `Environment="${key}=${systemdEscape(value)}"\n`)
+        .join("");
+}
+function systemdUnit(service) {
+    const workingDirectory = service.workingDirectory === undefined ? "" : `WorkingDirectory=${systemdQuotedValue(service.workingDirectory)}\n`;
+    const restart = service.restart === "on-failure" ? "Restart=on-failure\nRestartSec=2\n" : "Restart=no\n";
     return `[Unit]
-Description=Pi Web session daemon
-
+Description=${service.description}
+${dependencyLine("After", service.after)}${dependencyLine("Wants", service.wants)}
 [Service]
 Type=simple
-ExecStart=${serviceShellExecPrefix()} ${systemdServiceShellQuote(`exec ${executables.sessiond.command}`)}
-Restart=on-failure
-RestartSec=2
-
+${workingDirectory}${environmentLines(service.environment)}ExecStart=${serviceShellExecPrefix()} ${systemdServiceShellQuote(service.shellCommand)}
+${restart}
 [Install]
 WantedBy=default.target
 `;
 }
-function webUnit(options, executables) {
-    const configEnvironment = options.config === undefined ? "" : `Environment="PI_WEB_CONFIG=${systemdEscape(resolve(options.config))}"\n`;
-    return `[Unit]
-Description=Pi Web server
-After=${sessiondServiceName}
-Wants=${sessiondServiceName}
-
-[Service]
-Type=simple
-${configEnvironment}ExecStart=${serviceShellExecPrefix()} ${systemdServiceShellQuote(`exec ${executables.web.command}`)}
-Restart=on-failure
-RestartSec=2
-
-[Install]
-WantedBy=default.target
+function plistString(key, value, indent = "  ") {
+    return `${indent}<key>${xmlEscape(key)}</key>\n${indent}<string>${xmlEscape(value)}</string>\n`;
+}
+function plistProgramArguments(service) {
+    const args = ["/usr/bin/env", detectServiceShell().executable, "-lc", service.shellCommand];
+    return `  <key>ProgramArguments</key>\n  <array>\n${args.map((arg) => `    <string>${xmlEscape(arg)}</string>`).join("\n")}\n  </array>\n`;
+}
+function plistEnvironment(environment) {
+    const entries = Object.entries(environment);
+    if (entries.length === 0)
+        return "";
+    return `  <key>EnvironmentVariables</key>\n  <dict>\n${entries.map(([key, value]) => plistString(key, value, "    ")).join("")}  </dict>\n`;
+}
+function launchdLogPath(ref) {
+    return join(logDir, ref.logName);
+}
+function launchdPlist(service) {
+    const workingDirectory = service.workingDirectory === undefined ? "" : plistString("WorkingDirectory", service.workingDirectory);
+    const keepAlive = service.restart === "on-failure" ? "  <key>KeepAlive</key>\n  <dict>\n    <key>SuccessfulExit</key>\n    <false/>\n  </dict>\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>
+${plistString("Label", service.launchdLabel)}${plistProgramArguments(service)}${workingDirectory}${plistEnvironment(service.environment)}  <key>RunAtLoad</key>
+  <true/>
+${keepAlive}${plistString("StandardOutPath", launchdLogPath(service))}${plistString("StandardErrorPath", launchdLogPath(service))}</dict>
+</plist>
 `;
 }
 async function writeInitialConfig(options) {
@@ -216,33 +417,164 @@ async function writeInitialConfig(options) {
     }
     return configPath;
 }
+function systemdServicePath(ref) {
+    return join(systemdServiceDir, ref.systemdName);
+}
+function launchdPlistPath(ref) {
+    return join(launchdServiceDir, ref.launchdPlistName);
+}
+function serviceFileExists(backend, ref) {
+    return existsSync(backend.kind === "systemd" ? systemdServicePath(ref) : launchdPlistPath(ref));
+}
+function installedServiceRefs(backend) {
+    const installed = startOrder(allServiceRefs().filter((ref) => serviceFileExists(backend, ref)));
+    return installed.length === 0 ? productionServiceRefs() : installed;
+}
+async function installSystemdServices(services) {
+    const selected = new Set(services.map((service) => service.id));
+    const obsolete = stopOrder(allServiceRefs().filter((ref) => !selected.has(ref.id)));
+    for (const ref of obsolete) {
+        runQuiet("systemctl", ["--user", "disable", "--now", ref.systemdName]);
+        await rm(systemdServicePath(ref), { force: true });
+    }
+    await mkdir(systemdServiceDir, { recursive: true });
+    for (const service of services) {
+        await writeFile(systemdServicePath(service), systemdUnit(service));
+    }
+    const names = services.map((service) => service.systemdName);
+    run("systemctl", ["--user", "daemon-reload"], { check: true });
+    run("systemctl", ["--user", "enable", ...names], { check: true });
+    run("systemctl", ["--user", "restart", ...names], { check: true });
+}
+function launchdDomain() {
+    return `gui/${String(userInfo().uid)}`;
+}
+function launchdServiceTarget(ref) {
+    return `${launchdDomain()}/${ref.launchdLabel}`;
+}
+function launchdIsLoaded(ref) {
+    return capture("launchctl", ["print", launchdServiceTarget(ref)]).status === 0;
+}
+function launchdBootout(ref) {
+    runQuiet("launchctl", ["bootout", launchdServiceTarget(ref)]);
+}
+function launchdBootstrap(ref) {
+    run("launchctl", ["bootstrap", launchdDomain(), launchdPlistPath(ref)], { check: true });
+    run("launchctl", ["enable", launchdServiceTarget(ref)], { check: true });
+}
+function launchdStart(ref) {
+    if (!launchdIsLoaded(ref))
+        launchdBootstrap(ref);
+    run("launchctl", ["kickstart", launchdServiceTarget(ref)], { check: true });
+}
+async function installLaunchdServices(services) {
+    const selected = new Set(services.map((service) => service.id));
+    await mkdir(launchdServiceDir, { recursive: true });
+    await mkdir(logDir, { recursive: true });
+    for (const ref of stopOrder(allServiceRefs()))
+        launchdBootout(ref);
+    for (const ref of allServiceRefs().filter((candidate) => !selected.has(candidate.id))) {
+        await rm(launchdPlistPath(ref), { force: true });
+    }
+    for (const service of services) {
+        await writeFile(launchdPlistPath(service), launchdPlist(service));
+    }
+    for (const service of services)
+        launchdStart(service);
+}
+async function installNativeServices(backend, services) {
+    if (backend.kind === "systemd")
+        await installSystemdServices(services);
+    else
+        await installLaunchdServices(services);
+}
+async function uninstallSystemdServices() {
+    for (const ref of stopOrder(allServiceRefs())) {
+        runQuiet("systemctl", ["--user", "disable", "--now", ref.systemdName]);
+        await rm(systemdServicePath(ref), { force: true });
+    }
+    runQuiet("systemctl", ["--user", "daemon-reload"]);
+}
+async function uninstallLaunchdServices() {
+    for (const ref of stopOrder(allServiceRefs())) {
+        launchdBootout(ref);
+        await rm(launchdPlistPath(ref), { force: true });
+    }
+}
+async function uninstallNativeServices(backend) {
+    if (backend.kind === "systemd")
+        await uninstallSystemdServices();
+    else
+        await uninstallLaunchdServices();
+}
+function backendAvailabilityChecks(backend) {
+    if (backend.kind === "systemd")
+        return [["systemctl --user", ["systemctl", "--user", "--version"]]];
+    return [[`launchctl ${launchdDomain()}`, ["launchctl", "print", launchdDomain()]]];
+}
+function baseShellChecks(backend) {
+    const shell = serviceShellLabel();
+    const checks = [[`${shell} can find node >= 22`, serviceShellCommand(nodeVersionCheck())]];
+    if (backend.kind === "systemd")
+        checks.push([`systemd user ${shell} can find node >= 22`, systemdUserServiceShellCommand(nodeVersionCheck())]);
+    return checks;
+}
+function devInstallChecks(backend, root) {
+    const shell = serviceShellLabel();
+    const checks = [
+        [`${shell} can find npm`, serviceShellCommand(commandCheck("npm"), root)],
+        [`${shell} can find bash`, serviceShellCommand(commandCheck("bash"), root)],
+    ];
+    if (backend.kind === "systemd") {
+        checks.push([`systemd user ${shell} can find npm`, systemdUserServiceShellCommand(commandCheck("npm"), root)], [`systemd user ${shell} can find bash`, systemdUserServiceShellCommand(commandCheck("bash"), root)]);
+    }
+    return checks;
+}
+function installPreflightChecks(backend, mode, executables, devRoot) {
+    return [
+        ...backendAvailabilityChecks(backend),
+        ...baseShellChecks(backend),
+        ...(mode === "dev" && devRoot !== undefined ? devInstallChecks(backend, devRoot) : []),
+        ...(mode === "production" && executables !== undefined ? [...executables.web.checks, ...executables.sessiond.checks] : []),
+    ];
+}
 async function install(args) {
+    const backend = requireServiceBackend("pi-web install");
     const options = parseInstallOptions(args);
-    const executables = resolveServiceExecutables();
-    console.log("Running Pi Web install preflight checks...");
+    const devRoot = options.mode === "dev" ? devRootPath() : undefined;
+    if (devRoot !== undefined)
+        validateDevCheckout(devRoot);
+    const executables = options.mode === "production" ? resolveServiceExecutables(backend) : undefined;
+    console.log(`Running PI WEB ${options.mode} install preflight checks...`);
+    console.log(`Service backend: ${backend.label}`);
     console.log(`Service shell: ${describeServiceShell()}`);
-    if (!runChecks(installPreflightChecks(executables))) {
+    if (!runChecks(installPreflightChecks(backend, options.mode, executables, devRoot))) {
         printPathSetupAdvice();
         throw new Error("Install preflight checks failed. Fix the failed checks above, then run `pi-web doctor` for more detail.");
     }
     const configPath = await writeInitialConfig(options);
-    await mkdir(serviceDir, { recursive: true });
-    await writeFile(join(serviceDir, sessiondServiceName), sessiondUnit(executables));
-    await writeFile(join(serviceDir, webServiceName), webUnit(options, executables));
-    run("systemctl", ["--user", "daemon-reload"], { check: true });
-    run("systemctl", ["--user", "enable", "--now", sessiondServiceName], { check: true });
-    run("systemctl", ["--user", "enable", "--now", webServiceName], { check: true });
-    console.log(`\nPi Web is installed and starting.`);
+    const services = options.mode === "dev"
+        ? devServiceDefinitions(options, configPath, devRoot ?? devRootPath())
+        : productionServiceDefinitions(options, configPath, executables ?? resolveServiceExecutables(backend));
+    await installNativeServices(backend, services);
+    console.log(`\nPI WEB ${options.mode} services are installed and starting.`);
     console.log(`Config: ${configPath}`);
-    console.log(`Open: http://${options.host === "0.0.0.0" ? "127.0.0.1" : options.host}:${options.port}`);
-    const linger = isLingerEnabled();
-    if (linger === false) {
-        console.log("\nRecommended for server use: keep user services running after logout/reboot:");
-        console.log(`  sudo loginctl enable-linger ${userInfo().username}`);
+    if (options.mode === "dev") {
+        console.log("Open: http://127.0.0.1:8505");
     }
-    else if (linger === undefined) {
-        console.log("\nRecommended for server use: enable systemd user lingering so services survive logout/reboot:");
-        console.log(`  sudo loginctl enable-linger ${userInfo().username}`);
+    else {
+        console.log(`Open: http://${options.host === "0.0.0.0" ? "127.0.0.1" : options.host}:${options.port}`);
+    }
+    if (backend.kind === "systemd") {
+        const linger = isLingerEnabled();
+        if (linger === false) {
+            console.log("\nRecommended for server use: keep user services running after logout/reboot:");
+            console.log(`  sudo loginctl enable-linger ${userInfo().username}`);
+        }
+        else if (linger === undefined) {
+            console.log("\nRecommended for server use: enable systemd user lingering so services survive logout/reboot:");
+            console.log(`  sudo loginctl enable-linger ${userInfo().username}`);
+        }
     }
     console.log("\nUseful commands:");
     console.log("  pi-web status");
@@ -250,23 +582,55 @@ async function install(args) {
     console.log("  pi-web restart");
 }
 async function uninstall() {
-    run("systemctl", ["--user", "disable", "--now", webServiceName]);
-    run("systemctl", ["--user", "disable", "--now", sessiondServiceName]);
-    await rm(join(serviceDir, webServiceName), { force: true });
-    await rm(join(serviceDir, sessiondServiceName), { force: true });
-    run("systemctl", ["--user", "daemon-reload"]);
-    console.log("Pi Web systemd user services removed.");
+    const backend = requireServiceBackend("pi-web uninstall");
+    await uninstallNativeServices(backend);
+    console.log(`PI WEB ${backend.label} removed. Production and development service files were removed; config and data were left in place.`);
+}
+function systemdServiceAction(action, refs) {
+    const orderedRefs = action === "stop" ? stopOrder(refs) : startOrder(refs);
+    run("systemctl", ["--user", action, ...orderedRefs.map((ref) => ref.systemdName)], { check: action !== "status" });
+}
+function launchdServiceAction(action, refs) {
+    if (action === "status") {
+        for (const ref of refs) {
+            console.log(`\n== ${ref.launchdLabel} ==`);
+            run("launchctl", ["print", launchdServiceTarget(ref)]);
+        }
+        return;
+    }
+    if (action === "stop") {
+        for (const ref of stopOrder(refs))
+            launchdBootout(ref);
+        return;
+    }
+    if (action === "restart") {
+        for (const ref of stopOrder(refs))
+            launchdBootout(ref);
+    }
+    for (const ref of startOrder(refs))
+        launchdStart(ref);
 }
 function serviceAction(action) {
-    run("systemctl", ["--user", action, sessiondServiceName, webServiceName], { check: action !== "status" });
+    const backend = requireServiceBackend(`pi-web ${action}`);
+    const refs = installedServiceRefs(backend);
+    if (backend.kind === "systemd")
+        systemdServiceAction(action, refs);
+    else
+        launchdServiceAction(action, refs);
 }
 function logs() {
-    run("journalctl", ["--user", "-u", sessiondServiceName, "-u", webServiceName, "-f"]);
+    const backend = requireServiceBackend("pi-web logs");
+    const refs = installedServiceRefs(backend);
+    if (backend.kind === "systemd") {
+        run("journalctl", ["--user", ...refs.flatMap((ref) => ["-u", ref.systemdName]), "-f"]);
+        return;
+    }
+    run("tail", ["-F", ...refs.map((ref) => launchdLogPath(ref))]);
 }
 function serviceShellLabel() {
     return `${detectServiceShell().name} -lc`;
 }
-function systemdUserServiceShellCommand(command) {
+function systemdUserServiceShellCommand(command, cwd) {
     return [
         "systemd-run",
         "--user",
@@ -274,7 +638,7 @@ function systemdUserServiceShellCommand(command) {
         "--collect",
         "--pipe",
         "--quiet",
-        ...serviceShellCommand(command),
+        ...serviceShellCommand(command, cwd),
     ];
 }
 function commandCheck(command) {
@@ -286,25 +650,28 @@ function nodeVersionCheck() {
         "node -e \"const major = Number(process.versions.node.split('.')[0]); console.log(process.version); process.exit(major >= 22 ? 0 : 1);\"",
     ].join(" && ");
 }
-function installPreflightChecks(executables = resolveServiceExecutables()) {
-    const shell = serviceShellLabel();
-    return [
-        ["systemctl --user", ["systemctl", "--user", "--version"]],
-        [`${shell} can find node >= 22`, serviceShellCommand(nodeVersionCheck())],
-        [`systemd user ${shell} can find node >= 22`, systemdUserServiceShellCommand(nodeVersionCheck())],
-        ...executables.web.checks,
-        ...executables.sessiond.checks,
-    ];
-}
 function doctorChecks() {
     const shell = serviceShellLabel();
-    const executables = resolveServiceExecutables();
-    return [
-        ...installPreflightChecks(executables),
+    const backend = currentServiceBackend();
+    if (backend === undefined) {
+        return [
+            [`${shell} can find node >= 22`, serviceShellCommand(nodeVersionCheck())],
+            [`${shell} can find npm`, serviceShellCommand(commandCheck("npm"))],
+            [`${shell} can find pi`, serviceShellCommand(commandCheck("pi"))],
+        ];
+    }
+    const checks = [
+        ...backendAvailabilityChecks(backend),
+        ...baseShellChecks(backend),
         [`${shell} can find npm`, serviceShellCommand(commandCheck("npm"))],
         [`${shell} can find pi`, serviceShellCommand(commandCheck("pi"))],
-        [`systemd user ${shell} can find pi`, systemdUserServiceShellCommand(commandCheck("pi"))],
     ];
+    const executables = resolveServiceExecutables(backend);
+    checks.push(...executables.web.checks, ...executables.sessiond.checks);
+    if (backend.kind === "systemd") {
+        checks.push([`systemd user ${shell} can find pi`, systemdUserServiceShellCommand(commandCheck("pi"))]);
+    }
+    return checks;
 }
 function runChecks(checks) {
     let failed = false;
@@ -337,40 +704,69 @@ function printPathSetupAdvice() {
     }
     else if (shell.name === "zsh") {
         console.log("  Detected zsh. Put PATH setup for node/version managers/tools in ~/.zprofile, not only ~/.zshrc.");
-        console.log("  Avoid relying on prompt hooks; Pi Web services run non-interactive login shells.");
+        console.log("  Avoid relying on prompt hooks; PI WEB services run non-interactive login shells.");
     }
     else {
         console.log("  Detected fish. Prefer universal PATH setup such as `fish_add_path -U ...` for tools needed by services or agents.");
-        console.log("  Avoid relying on prompt hooks; Pi Web services run non-interactive login shells.");
+        console.log("  Avoid relying on prompt hooks; PI WEB services run non-interactive login shells.");
     }
 }
 function doctor() {
+    const backend = currentServiceBackend();
+    console.log(`Platform: ${platformLabel()}`);
+    console.log(`Service backend: ${backend?.label ?? "manual run only"}`);
     console.log(`Service shell: ${describeServiceShell()}`);
+    if (backend === undefined) {
+        console.log(`- Native user service checks skipped on ${platformLabel()}`);
+    }
     const ok = runChecks(doctorChecks());
-    const linger = isLingerEnabled();
-    if (linger === true) {
-        console.log("✓ systemd user lingering enabled");
+    const nodePtySpawnHelperOk = printNodePtyDarwinSpawnHelperCheck();
+    if (supportsSystemdUserServices()) {
+        const linger = isLingerEnabled();
+        if (linger === true) {
+            console.log("✓ systemd user lingering enabled");
+        }
+        else if (linger === false) {
+            console.log("✗ systemd user lingering disabled");
+            console.log(`  Recommended on servers: sudo loginctl enable-linger ${userInfo().username}`);
+        }
+        else {
+            console.log("? systemd user lingering unknown");
+            console.log(`  Recommended on servers: sudo loginctl enable-linger ${userInfo().username}`);
+        }
     }
-    else if (linger === false) {
-        console.log("✗ systemd user lingering disabled");
-        console.log(`  Recommended on servers: sudo loginctl enable-linger ${userInfo().username}`);
+    else if (backend?.kind === "launchd") {
+        console.log("- user services start at login with LaunchAgents");
     }
     else {
-        console.log("? systemd user lingering unknown");
-        console.log(`  Recommended on servers: sudo loginctl enable-linger ${userInfo().username}`);
+        console.log(`- systemd user lingering skipped on ${platformLabel()}`);
     }
     if (!ok) {
         console.log("\nIf a command works in your terminal but fails here, make sure your service shell login files set PATH the same way.");
-        console.log("If a bundled entrypoint is not accessible, reinstall or update the Pi Web package.");
+        if (backend?.kind === "systemd")
+            console.log("If a bundled entrypoint is not accessible, reinstall or update the PI WEB package.");
         printPathSetupAdvice();
-        process.exitCode = 1;
     }
+    if (ok && backend === undefined) {
+        console.log(`\n${manualRunAdvice()}`);
+    }
+    if (!ok || !nodePtySpawnHelperOk)
+        process.exitCode = 1;
+}
+function printNodePtyDarwinSpawnHelperCheck() {
+    const result = formatNodePtyDarwinSpawnHelperCheck(checkNodePtyDarwinSpawnHelper());
+    for (const line of result.lines)
+        console.log(line);
+    return result.ok;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function help() {
-    console.log(`Pi Web
+    console.log(`PI WEB
 
 Usage:
-  pi-web install [--host 127.0.0.1] [--port 8504] [--config ~/.config/pi-web/config.json]
+  pi-web install [--dev] [--host 127.0.0.1] [--port 8504] [--config ~/.config/pi-web/config.json]
   pi-web uninstall
   pi-web start|stop|restart|status|logs
   pi-web doctor
@@ -378,6 +774,9 @@ Usage:
 Recommended install:
   npm install -g @jmfederico/pi-web
   pi-web install
+
+Development service install from a checkout:
+  pi-web install --dev
 `);
 }
 async function main() {